Embedded iPaaSUnified API

Order Fulfillment Updates

Get order information from users’ ecommerce platforms using Alloy’s Unified API.

Suggest Edits

Use Case Overview

Key Model(s) and FieldsSupported Applications
Orders

orderStatus
lineItems
customer
fulfillmentStatus		Shopify, Adobe Commerce (formerly Magento), BigCommerce, WooCommerce, Salesforce Commerce Cloud, SquareSpace, eBay

📘

Data Flow: Commerce Platform -> Your App

This is a read integration. In this example, you can GET target resources to ensure that merchants can respond to their customers' order inquiries quickly and accurately.

How to build this use case with Alloy's Unified API

1. Create a Connection

To get started, you'll need to first implement Alloy's Unified API and create a connection. A connection represents each time an end user links an app to Alloy's Unified API. See Creating a Connection in our Unified API Quickstart.

Your end-users authenticate integrations using the Alloy Modal.

Your end-users authenticate integrations using the Alloy Modal.

If you’ve already done this, read on!

2. Get all orders from a user’s commerce platform

To retrieve a full list of a merchant’s orders, use the [GET List Orders] endpoint to do so in a standardized format. In Alloy’s Unified API, the orders object includes orderStatus, lineItems, customer, shippingAddress and more.

Your request should look like this:

curl --request GET \
     --url 'https://embedded.runalloy.com/2024-03/one/commerce/orders?credentialId=CREDENTIAL_ID' \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json'

Which will return the following response:

{
  "orders": [
    {
      "remoteId": "1234567890123",
      "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
      "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
      "remoteDeleted": false,
      "createdAt": "2024-02-22T11:17:53.264Z",
      "updatedAt": "2024-02-22T13:54:03.445Z",
      "orderNumber": "2001",
      "orderStatus": "Pending",
      "fulfillmentStatus": "unfulfilled",
      "totalShipping": "5.00",
      "totalDiscount": "1.00",
      "totalTax": "0.50",
      "totalPrice": "15.00",
      "currency": "USD",
      "lineItems": [
        {
          "quantity": 2,
          "productId": "9876543210987",
          "lineItemId": "12345678912345",
          "price": "7.50",
          "unitCost": "5.00",
          "currency": "USD",
          "variantId": "12312312312312",
          "title": "Custom T-Shirt",
          "sku": "SKU12345"
        }
      ],
      "paymentStatus": "Pending",
      "billingAddress": {
        "firstName": "Alice",
        "lastName": "Smith",
        "address2": "Apt 2",
        "city": "New York",
        "phone": "1234567890",
        "address1": "123 Main Street",
        "countryCode": "US",
        "postalCode": "10001",
        "region": "NY"
      },
      "shippingAddress": {
        "firstName": "Alice",
        "lastName": "Smith",
        "address2": "Apt 2",
        "city": "New York",
        "phone": "1234567890",
        "address1": "123 Main Street",
        "countryCode": "US",
        "postalCode": "10001",
        "region": "NY"
      },
      "customer": {
        "customerId": "9876543210987",
        "firstName": "Alice",
        "lastName": "Smith",
        "phone": "1234567890",
        "email": "[email protected]"
      },
      "id": "a1b2c3d4-e5f6-7g8h-9i0j-1k2l3m4n5o6p"
    },
    {
      "remoteId": "9876543210123",
      "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
      "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
      "remoteDeleted": false,
      "createdAt": "2024-02-22T11:17:53.264Z",
      "updatedAt": "2024-02-22T13:54:03.445Z",
      "orderNumber": "2002",
      "orderStatus": "Shipped",
      "fulfillmentStatus": "fulfilled",
      "totalShipping": "4.00",
      "totalDiscount": "0.50",
      "totalTax": "0.75",
      "totalPrice": "20.00",
      "currency": "USD",
      "lineItems": [
        {
          "quantity": 1,
          "productId": "8765432109876",
          "lineItemId": "23456789123456",
          "price": "15.00",
          "unitCost": "10.00",
          "currency": "USD",
          "variantId": "23423423423423",
          "title": "Sporty Jacket",
          "sku": "SKU54321"
        }
      ],
      "paymentStatus": "Paid",
      "billingAddress": {
        "firstName": "Bob",
        "lastName": "Johnson",
        "address2": "",
        "city": "Los Angeles",
        "phone": "0987654321",
        "address1": "456 Another St",
        "countryCode": "US",
        "postalCode": "90001",
        "region": "CA"
      },
      "shippingAddress": {
        "firstName": "Bob",
        "lastName": "Johnson",
        "address2": "",
        "city": "Los Angeles",
        "phone": "0987654321",
        "address1": "456 Another St",
        "countryCode": "US",
        "postalCode": "90001",
        "region": "CA"
      },
      "customer": {
        "customerId": "8765432109876",
        "firstName": "Bob",
        "lastName": "Johnson",
        "phone": "0987654321",
        "email": "[email protected]"
      },
      "id": "b2c3d4e5-f6g7-h8i9-j0k1-2l3m4n5o6p7q"
    },
    {
      "remoteId": "3216549870123",
      "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
      "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
      "remoteDeleted": false,
      "createdAt": "2024-02-22T11:17:53.264Z",
      "updatedAt": "2024-02-22T13:54:03.445Z",
      "orderNumber": "2003",
      "orderStatus": "Cancelled",
      "fulfillmentStatus": "unfulfilled",
      "totalShipping": "6.00",
      "totalDiscount": "2.00",
      "totalTax": "1.00",
      "totalPrice": "12.00",
      "currency": "USD",
      "lineItems": [
        {
          "quantity": 3,
          "productId": "7654321098765",
          "lineItemId": "34567891234567",
          "price": "4.00",
          "unitCost": "2.50",
          "currency": "USD",
          "variantId": "34534534534534",
          "title": "Elegant Hat",
          "sku": "SKU98765"
        }
      ],
      "paymentStatus": "Refunded",
      "billingAddress": {
        "firstName": "Charlie",
        "lastName": "Davis",
        "address2": "Suite 101",
        "city": "Chicago",
        "phone": "0123456789",
        "address1": "789 Third Ave",
        "countryCode": "US",
        "postalCode": "60601",
        "region": "IL"
      },
      "shippingAddress": {
        "firstName": "Charlie",
        "lastName": "Davis",
        "address2": "Suite 101",
        "city": "Chicago",
        "phone": "0123456789",
        "address1": "789 Third Ave",
        "countryCode": "US",
        "postalCode": "60601",
        "region": "IL"
      },
      "customer": {
        "customerId": "7654321098765",
        "firstName": "Charlie",
        "lastName": "Davis",
        "phone": "0123456789",
        "email": "[email protected]"
      },
      "id": "c3d4e5f6-g7h8-i9j0-k1l2-3m4n5o6p7q8r"
    }
  ]
}

As you can see, your response payload will match the structure of Alloy’s common model for orders, rather than the structure of the source application (ex. Shopify, Magento.)

From here, you can write the app logic to sync the orders to your application’s database.

3. Narrow your list (optional)

You can filter by query parameters to access a part of the list — for example:

  • fulfillmentStatus can be used to only retrieve orders that are open or don't have a known fulfillment
  • currency can be used to retrieve orders with a specific currency

See our API reference for all available params. If you were filtering by orderStatus, your request would look like this:

Here's what a request for orders with a specific fulfillmentStatus looks like:

curl --request GET \
     --url 'https://embedded.runalloy.com/2024-03/one/commerce/orders?credentialId=CREDENTIAL_ID&fulfillmentStatus=unfulfilled' \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json'

Help merchants respond to order inquiries

By reading order data from a merchant’s ecommerce platform, you can present them with the information they need to provide their customers with status updates directly from your application.

Updated about 1 month ago