Importing 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.

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:

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

Access Your Credentials

1. Log in to your Parsel account at https://parsel.app
2. Navigate to Settings → Orders at https://parsel.app/settings/orders
3. 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:

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

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

1. Prepare your payload: Convert your order data to a JSON string
2. Use your base64-encoded secret string directly in your HMAC calculation
3. Generate HMAC-SHA256 using your secret and the request body
4. 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

Step 3: Submit Your Order

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

Endpoint

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

Required Headers

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