Import Orders

Parsel's Custom Order Ingestion enables you to push orders directly to Parsel without using pre-built integrations. This is a webhook-based integration where you send order data to Parsel's API endpoint. Each order you submit is processed asynchronously and can be managed through the Parsel dashboard.

If you're using Shopify, Parsel offers a direct Shopify integration that automatically syncs your orders. You can set this up in the Parsel dashboard https://parsel.app/settings/storefronts

Signature Verification

Order import uses HMAC-SHA256 signature verification to authenticate webhook requests and ensure payload integrity.

When you send order data to Parsel's webhook endpoint, you must include a computed signature in the request headers.

How to import orders

Step 1: Obtain Your Credentials

Before you can import orders, you need to obtain two credentials from the Parsel dashboard that will be used as request headers:

Account Identifier - Used in the X-Oregano-Organization-Id header
Signing Secret - Used to compute the X-CustomOrderSource-Signature header

Access Your Credentials

Log in to your Parsel account at https://parsel.app
Navigate to Settings → Orders at https://parsel.app/settings/orders
In the Import Order section, you'll find both your Account Identifier and Signing Secret

Renew your Signing Secret

If you need to renew your signing secret:

Go to https://parsel.app/settings/orders
Click Renew Secret in the Custom Order Ingestion section
Copy the generated secret and store it securely

Store your signing secret securely! You'll need it to sign all webhook requests. If you regenerate the secret, all existing webhook integrations will need to be updated with the new secret.

Example Secret:

Sgt5mu5MsfB4WiJ+Vlkb0FobRQHTndtTex5NQlm0a4w=

Step 2: Compute the HMAC Signature

For each webhook request, you must compute an HMAC-SHA256 signature of the request payload using your webhook secret.

Signature Algorithm

Prepare your payload: Convert your order data to a JSON string
Use your base64-encoded secret string directly in your HMAC calculation
Generate HMAC-SHA256 using your secret and the request body
Encode as hex: Convert the HMAC result to a hexadecimal string

Example: Signature Computation

Your Base64-Encoded Secret

Sgt5mu5MsfB4WiJ+Vlkb0FobRQHTndtTex5NQlm0a4w=

Sample Order Payload

{
  "id": "order_id_test_1",
  "name": "#ORDER NAME 1",
  "tags": [
    "TAG 1",
    "TAG 2"
  ],
  "shippingAddress": {
    "id": "982093UR90328R",
    "zip": "62704",
    "city": "SPRINGFIELD",
    "phone": "+1-217-555-0123",
    "company": "My Company",
    "country": "US",
    "address1": "22 Elm Street",
    "address2": "Suite 101",
    "lastName": "Doe",
    "latitude": 0,
    "province": "Illinois",
    "firstName": "Jane",
    "longitude": 0,
    "provinceCode": "IL",
    "countryCodeV2": "US",
    "coordinatesValidated": true
  },
  "fulfillmentOrders": [
    {
      "id": "ful_ord_1",
      "status": "OPEN",
      "lineItems": [
        {
          "id": "line_item_00832",
          "sku": "CUS-SKU-22-GHI",
          "image": {
            "id": "e",
            "url": "https://placehold.co/600x400@2x.png",
            "width": 1800,
            "height": 1800,
            "altText": "Brown Leather Belt"
          },
          "weight": {
            "unit": "POUNDS",
            "value": 1
          },
          "variant": {
            "price": 45,
            "product": {
              "id": ""
            },
            "inventoryItem": {
              "measurement": {
                "weight": {
                  "unit": "POUNDS",
                  "value": 1
                }
              },
              "countryCodeOfOrigin": "",
              "harmonizedSystemCode": ""
            }
          },
          "productTitle": "Leather Belt",
          "variantTitle": "Brown-L",
          "totalQuantity": 1,
          "requiresShipping": true,
          "remainingQuantity": 1,
          "financialSummaries": {
            "originalUnitPriceSet": {
              "shopMoney": {
                "amount": 45,
                "currencyCode": "USD"
              }
            },
            "approximateDiscountedUnitPriceSet": {
              "shopMoney": {
                "amount": 0,
                "currencyCode": "USD"
              }
            }
          }
        }
      ],
      "destination": {
        "id": "1f54e6e9-2370-41ff-bcd0-0f9fb998b689",
        "zip": "78701",
        "city": "Austin",
        "email": "",
        "phone": "+1-555-999-0000",
        "company": "",
        "address1": "500 Main St",
        "address2": "Unit 5",
        "lastName": "Johnson",
        "province": "Texas",
        "firstName": "Sarah",
        "countryCode": "US"
      },
      "deliveryMethod": {
        "methodType": "SHIPPING"
      },
      "assignedLocation": {
        "name": "West Warehouse"
      },
      "internationalDuties": {
        "incoterm": "DAP"
      }
    }
  ]
}

Expected Signature

When you send this payload, the computed HMAC-SHA256 signature in hexadecimal format should be:

31ffffc7aa098d32df3b2b17b1a87af8979c2cbbfc42ef80d7d5e811eefeaceb

The signature must be computed from the exact JSON body that will be sent in the request. Any differences in whitespace, formatting, or field order will cause verification to fail.

Step 3: Submit Your Order

Once you have computed the signature, you can submit your order to the custom order ingestion endpoint.

Endpoint

POST https://api.oregano.saltbox.com/webhook/custom-orders

Required Headers

X-Oregano-Organization-Id: Your Account Identifier (obtained from Step 1)
X-CustomOrderSource-Signature: The computed HMAC-SHA256 signature in hexadecimal format (computed in Step 2 using your Signing Secret)

On this page