openapi: 3.1.0 info: version: 1.0.0 title: Integrations Introduction description: | You can integrate Commerce with your external systems like enterprise resource planning, order management, fulfilment, and other systems, ensuring that buying is quick and easy for your shoppers. Events are actions that occur in your commerce workflow, such as a customer changing their address or an order changing status from created to paid. You can create custom functions that perform additional processing outside of Commerce, and create integrations so that when an event occurs in your store, the custom function is run. For example: - When a customer updates their address, the Customer Relationship Management system is updated with the change. - When an order status changes to paid, the affected stock in an inventory management system is reduced by the number of items in the order. Events are processed concurrently. This means that events may not be delivered in the order they are created. For example, if the status of an order is updated multiple times, the events may not be delivered in the same sequence they were updated. Integration events operate on an "at least once" delivery policy. We aim to deliver messages within 30 minutes or less. Ensure that you design your receiving code accordingly. :::note For a list of all the events that can be used, see [Observable Events](#observable-events). ::: You can integrate Commerce with your external systems using: - Webhooks - Message Queuing Services ### Webhooks You can use Webhooks to deliver Commerce events to a configured HTTP endpoint. ### Message Queuing Services You can deliver Commerce events to messages queues through the following message queuing services: - Amazon Simple Queuing Service (SQS) - Message queuing services that support the Message Simple Text Orientated Messaging Protocol (STOMP), for example, Amazon MQ. :::note You can integrate Amazon SQS and message queuing services that support STOMP through the Integrations API. You can view the integration details in Commerce Manager > **SYSTEM** > **Store Settings** > **Webhooks**. For more information, see [Create an integration](/docs/api/integrations/create-integration). ::: ### Integration Types Commerce supports the following integration types: - Using [webhooks](/docs/api/integrations/create-integration), you can have Commerce deliver events to a configured HTTP endpoint. :::caution Webhooks that return anything other than a 2XX status code, or take more than 10 seconds to respond, are considered failed. - Using [message queuing services](#message-queuing-services), you can deliver Commerce events to a message queue. The advantages of using message queuing services over webhooks are: - A temporary failure of a webhook endpoint can result in lost events. However, if messages are on your own queue, you can leave the event on the queue to retry later. - If events take a long time to process, a webhook can timeout, but delivery to a queue is always going to take the same amount of time. ::: ### Webhooks An integration with an `integration_type` of [`webhook`](/docs/api/integrations/create-integration) delivers its events to a configured HTTP endpoint. ### Message Queuing Services Elastic Path allows you to integrate with the following message queuing services: - Amazon Simple Message Queuing Service (SQS). - Message queuing services that use Simple Text Orientated Messaging Protocol (STOMP), for example, Amazon MQ. :::caution You can integrate Amazon SQS and message queuing services that support STOMP through the Integrations API. You can view the integration details in Commerce Manager > **SYSTEM** > **Store Settings** > **Webhooks**. For more information, see [Create an integration](/docs/api/integrations/create-integration). ::: #### Amazon Simple Message Queuing Service (SQS) An integration with an `integration_type` of [`aws_sqs`](/docs/api/integrations/create-integration) delivers its events directly into the configured AWS SQS queue. These messages can be processed by any appropriate means, such as a Lambda function. For more information about creating Simple Queue Service (SQS) queues, see the [Simple Queue Service (SQS)](https://elasticpath.dev/guides/How-To/Integrations/sqs-queues) and [SQS Events with CloudFormation](https://elasticpath.dev/guides/How-To/Integrations/sqs-queues-cloudformation) sections. #### Simple Text Orientated Messaging Protocol (STOMP) An integration with the [`stomp`](/docs/api/integrations/create-integration) integration type delivers its events directly into a configured queue. Any message queuing service that uses STOMP, such as Amazon MQ, can process these messages. For more information, see the documentation provided with the message queuing service you are using. ### Webhooks The payload delivered to your webhook `url` contains information about the fired event. The payload attributes and types are defined in the following table. | Attribute | Type | Description | | :------------- | :------------------------------- | :------------------------------------------------------------------------------------------------ | | `id` | `string` | A unique ID for this event. | | `integration` | `object` | The events `integration_type` being fired. | | `triggered_by` | `string` | The [observable events](#observable-events) that triggered this event. | | `attempt` | `integer` | The number of attempts to deliver this event. | | `resources` | `string` | The resources affected by this event. This field is now deprecated. Please use `payload` instead. | | `payload` | `object` | The resources affected by this event. | :::note Store-level events contain `store_id` and `org_id` whereas, organization-level events contain only `org_id`. ::: ### Example: Typical payload The following example payload [observes](#observable-events) the `order.paid` event. The configured URL receives the following payload. ```javascript { "id": "21a361c9-b117-4d16-be2d-5ed2dbdaa95b", "triggered_by": "order.paid", "attempt": 1, "integration": { "id": "af7bbcc7-f77f-4a8f-abdb-4f039c5c9d81", "integration_type": "webhook", "name": "Order paid notification", "description": "Fire an event on order paid" }, "resources": "{\"data\":{\"type\":\"order\",\"id\":\"1d67160d-dacb-43ed-80ef-c3c4e7ddf764\",\"status\":\"complete\",\"payment\":\"paid\",\"shipping\":\"unfulfilled\",\"customer\":{\"name\":\"Ron Swanson\",\"email\":\"ron.swanson@moltin.com\"},\"shipping_address\":{\"first_name\":\"Jack\",\"last_name\":\"Macdowall\",\"phone_number\":\"123456789\",\"company_name\":\"Macdowalls\",\"line_1\":\"Second Floor, British India House\",\"line_2\":\"15 Carliol Square\",\"city\":\"Newcastle upon Tyne\",\"postcode\":\"NE1 6UF\",\"county\":\"Tyne and Wear\",\"country\":\"GB\",\"instructions\":\"Leave in porch\"},\"billing_address\":{\"first_name\":\"Jack\",\"last_name\":\"Macdowall\",\"company_name\":\"Macdowalls\",\"line_1\":\"Second Floor, British India House\",\"line_2\":\"15 Carliol Square\",\"city\":\"Newcastle upon Tyne\",\"postcode\":\"NE1 6UF\",\"county\":\"Tyne and Wear\",\"country\":\"GB\"},\"links\":{},\"meta\":{\"display_price\":{\"with_tax\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"},\"without_tax\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"},\"tax\":{\"amount\":0,\"currency\":\"GBP\",\"formatted\":\"£0.00\"}},\"timestamps\":{\"created_at\":\"2019-07-04T11:12:23Z\",\"updated_at\":\"2019-07-04T11:12:23Z\"}},\"relationships\":{\"items\":{\"data\":[{\"type\":\"item\",\"id\":\"395763ee-1878-4aa0-a7a2-8d4877310d6b\"}]}}},\"included\":{\"items\":[{\"type\":\"order_item\",\"id\":\"395763ee-1878-4aa0-a7a2-8d4877310d6b\",\"quantity\":1,\"product_id\":\"4f28f222-aa5b-442c-9ce9-c223dc7cf15a\",\"name\":\"Spam Fritters\",\"sku\":\"spam-fritters-0716\",\"unit_price\":{\"amount\":10000,\"currency\":\"GBP\",\"includes_tax\":false},\"value\":{\"amount\":10000,\"currency\":\"GBP\",\"includes_tax\":false},\"links\":{},\"meta\":{\"display_price\":{\"with_tax\":{\"unit\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"},\"value\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"}},\"without_tax\":{\"unit\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"},\"value\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"}},\"tax\":{\"unit\":{\"amount\":0,\"currency\":\"GBP\",\"formatted\":\"£0.00\"},\"value\":{\"amount\":0,\"currency\":\"GBP\",\"formatted\":\"£0.00\"}}},\"timestamps\":{\"created_at\":\"2019-07-04T11:12:23Z\",\"updated_at\":\"2019-07-04T11:12:23Z\"}},\"relationships\":{\"cart_item\":{\"data\":{\"type\":\"cart_item\",\"id\":\"a498b15a-2cc7-49ea-93b3-22143bb403ac\"}}}}]}}", "payload": { "data": { "type": "order", "id": "1d67160d-dacb-43ed-80ef-c3c4e7ddf764", "status": "complete", "payment": "paid", "shipping": "unfulfilled", "customer": { "name": "Ron Swanson", "email": "ron.swanson@moltin.com" }, "shipping_address": { "first_name": "Jack", "last_name": "Macdowall", "phone_number": "123456789", "company_name": "Macdowalls", "line_1": "Second Floor, British India House", "line_2": "15 Carliol Square", "city": "Newcastle upon Tyne", "postcode": "NE1 6UF", "county": "Tyne and Wear", "country": "GB", "instructions": "Leave in porch" }, "billing_address": { "first_name": "Jack", "last_name": "Macdowall", "company_name": "Macdowalls", "line_1": "Second Floor, British India House", "line_2": "15 Carliol Square", "city": "Newcastle upon Tyne", "postcode": "NE1 6UF", "county": "Tyne and Wear", "country": "GB" }, "links": {}, "meta": { "display_price": { "with_tax": { "amount": 10000, "currency": "GBP", "formatted": "£100.00" }, "without_tax": { "amount": 10000, "currency": "GBP", "formatted": "£100.00" }, "tax": { "amount": 0, "currency": "GBP", "formatted": "£0.00" } }, "timestamps": { "created_at": "2019-07-04T11:12:23Z", "updated_at": "2019-07-04T11:12:23Z" } }, "relationships": { "items": { "data": [ { "type": "item", "id": "395763ee-1878-4aa0-a7a2-8d4877310d6b" } ] } } }, "included": { "items": [ { "type": "order_item", "id": "395763ee-1878-4aa0-a7a2-8d4877310d6b", "quantity": 1, "product_id": "4f28f222-aa5b-442c-9ce9-c223dc7cf15a", "name": "Spam Fritters", "sku": "spam-fritters-0716", "unit_price": { "amount": 10000, "currency": "GBP", "includes_tax": false }, "value": { "amount": 10000, "currency": "GBP", "includes_tax": false }, "links": {}, "meta": { "display_price": { "with_tax": { "unit": { "amount": 10000, "currency": "GBP", "formatted": "£100.00" }, "value": { "amount": 10000, "currency": "GBP", "formatted": "£100.00" } }, "without_tax": { "unit": { "amount": 10000, "currency": "GBP", "formatted": "£100.00" }, "value": { "amount": 10000, "currency": "GBP", "formatted": "£100.00" } }, "tax": { "unit": { "amount": 0, "currency": "GBP", "formatted": "£0.00" }, "value": { "amount": 0, "currency": "GBP", "formatted": "£0.00" } } }, "timestamps": { "created_at": "2019-07-04T11:12:23Z", "updated_at": "2019-07-04T11:12:23Z" } }, "relationships": { "cart_item": { "data": { "type": "cart_item", "id": "a498b15a-2cc7-49ea-93b3-22143bb403ac" } } } } ] } }, "configuration": { "secret_key": "secret_squirrel", "url": "https://webhook.url" } } ``` ### Example: Deleted resources payload When resources are deleted and you observe an event, you receive a payload which **only** contains the resource type and ID. ```javascript { "id": "c138854a-5311-4543-a368-01e099f5519b", "triggered_by": "product.deleted", "attempt": 1, "integration": { "id": "4596d5e1-26b6-444a-964d-2b6ec46477fd", "integration_type": "webhook", "name": "Product deleted notification", "description": "Let me know when products are deleted from my store." }, "resources": { "id": "a34a378b-2c39-41e4-a240-6b7e65f5bb55", "type": "product" }, "payload": { "type": "product", "id": "a34a378b-2c39-41e4-a240-6b7e65f5bb55" }, "configuration": { "secret_key": "secret_squirrel", "url": "https://webhook.url" } } ``` ### Message Queue Services The payload of messages delivered to your message queue contains information about the fired event. The information takes the form of a standard cloud event. The following table defines the payload attributes and types: | Attribute | Type | Description | | :-------------- | :------------------------------- | :---------------------------------------------------------------------- | | `id` | `string` | A unique ID for this event. | | `integrationid` | `string` | The ID of the integration being fired. | | `type` | `string` | The [observable event](#observable-events) that triggered this event. | | `data` | `object` | The resource affected by this event. | #### Example: Typical payload The following example payload [observes](#observable-events) the `cart.updated` event. The configured queue receives the following message payload: ```javascript { "data": { "description": "", "id": "a-cart-id", "links": { "self": "https://epcc-integration.global.ssl.fastly.net/v2/carts/a-cart-id" }, "meta": { "display_price": { "discount": { "amount": 0, "currency": "USD", "formatted": "$0.00" }, "tax": { "amount": 0, "currency": "USD", "formatted": "$0.00" }, "with_tax": { "amount": 200, "currency": "USD", "formatted": "$2.00" }, "without_tax": { "amount": 200, "currency": "USD", "formatted": "$2.00" } }, "timestamps": { "created_at": "2021-05-17T11:30:07Z", "expires_at": "2021-05-24T11:31:08Z", "updated_at": "2021-05-17T11:31:08Z" } }, "name": "Cart", "relationships": { "customers": {}, "items": { "data": [ { "id": "4d28bc2b-9db3-4c96-801b-df0ac5b41552", "type": "custom_item" } ] } }, "type": "cart" }, "datacontenttype": "application/json", "id": "9a21fb54-6c3b-432a-bade-82a60da6b59a", "integrationid": "e17db0d8-467b-4bf3-9c26-3dfe8b96e9d7", "source": "https://epcc-integration.global.ssl.fastly.net", "specversion": "1.0", "storeid": "b33e328f-31a8-4d57-b0a3-ebf1039b3756", "type": "cart.updated" } ``` ### Example: Deleted resources payload When resources are deleted, and you observe an event, the resource delivered in the message only contains the resource type and ID. ```javascript { "data": { "id": "a2733958-1273-4385-9a05-f1ca7684f760", "type": "product" }, "datacontenttype": "application/json", "id": "efca76df-9fc1-4434-ba26-82339d9b723c", "integrationid": "e17db0d8-467b-4bf3-9c26-3dfe8b96e9d7", "source": "https://epcc-integration.global.ssl.fastly.net", "specversion": "1.0", "storeid": "b33e328f-31a8-4d57-b0a3-ebf1039b3756", "type": "product.deleted" } ``` ### Observable Events You can pass multiple observable keys to the `observes` field of the [integration object](/docs/api/integrations/create-integration), or you can create individual events. You can use an array when you handle multiple webhooks at the same URL.
Entity/Resource | Action | Observable Key | Store/Organization |
---|---|---|---|
Address | Created | address.created |
Store |
Updated | address.updated |
Store | |
Deleted | address.deleted |
Store | |
Account | Created | account.created |
Store |
Updated | account.updated |
Store | |
Deleted | account.deleted |
Store | |
Account Member | Created | account-member.created |
Store |
Updated | account-member.updated |
Store | |
Deleted | account-member.deleted |
Store | |
Account Membership | Created | account-membership.created |
Store |
Updated | account-membership.updated |
Store | |
Deleted | account-membership.deleted |
Store | |
Carts | Updated | cart.updated |
Store |
Deleted | cart.deleted |
Store | |
Currency | Created | currency.created |
Store |
Updated | currency.updated |
Store | |
Deleted | currency.deleted |
Store | |
Customer | Created | customer.created |
Store |
Updated | customer.updated |
Store | |
Deleted | customer.deleted |
Store | |
Custom API Entries | Created | customAPIEntryType.created |
Store |
Updated | customAPIEntryType.updated |
Store | |
Deleted | customAPIEntryType.deleted |
Store | |
File | Created | file.created |
Store |
Deleted | file.deleted |
Store | |
Integration (events) | Created | integration.created |
Store, Organization |
Updated | integration.updated |
Store, Organization | |
Deleted | integration.deleted |
Store, Organization | |
One-Time Password Token Request | Created | one-time-password-token-request.created |
Store |
Order Events | |||
/checkout | Created | order.created |
Store |
/orders/:id/payments | Updated | order.updated / order.paid . The event order.paid is triggered when the payment status is paid . The event order.updated is triggered when the order is captured, completed, refunded, anonymized, or updated. |
Store |
/orders/:id | Fulfilled/Canceled | order.fulfilled / order.cancelled |
Store |
/orders/:id/payments | Authorized | order.authorized |
Store |
/orders/:id/transactions/:id/capture | Paid/Captured | order.paid / order.updated . The event order.paid is triggered when the order status is completed and captured, and the payment status is paid . The event order.updated is triggered when the order is captured, completed, refunded, anonymized, or updated. |
Store |
/orders/:id/transactions/:id/refund | Refunded | order.refunded |
Store |
Payment Gateway | Updated | payment-gateway.updated |
Store |
Catalog releases | Created | catalog-release.created |
Store, Organization |
Updated | catalog-release.updated |
Store, Organization | |
Deleted | catalog-release.deleted |
Store, Organization | |
Catalog rules | Created | catalog-rule.created |
Store |
Updated | catalog-rule.updated |
Store | |
Deleted | catalog-rule.deleted |
Store | |
Settings | Created | settings.created |
Store |
Updated | settings.updated |
Store | |
Stock Transaction | Created | stock-transaction.created |
Store |
Transaction | Created | transaction.created |
Store |
Updated | transaction.updated |
Store | |
Subscriptions | You can integrate Subscriptions with external systems like enterprise resource planning, fulfilment and other systems. For example, when a subscriber updates their address, the Customer Relationship Management system is updated with the change. See Subscriptions. | ||
User Authentication Info | Created | user-authentication-info.created |
Store |
Updated | user-authentication-info.updated |
Store | |
Deleted | user-authentication-info.deleted |
Store |