Integrations Introduction
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.
For a list of all the events that can be used, see 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.
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.
Integration Types
Commerce supports the following integration types:
- Using webhooks, you can have Commerce deliver events to a configured HTTP endpoint.
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, 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 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.
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.
Amazon Simple Message Queuing Service (SQS)
An integration with an integration_type of aws_sqs 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) and SQS Events with CloudFormation sections.
Simple Text Orientated Messaging Protocol (STOMP)
An integration with the stomp 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 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. |
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 the order.paid event. The configured URL receives the following payload.
{
"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.
{
"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 that triggered this event. |
data | object | The resource affected by this event. |
Example: Typical payload
The following example payload observes the cart.updated event. The configured queue receives the following message payload:
{
"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.
{
"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, 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 |
| 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 |
| Authorized | order.authorized | Store | |
| Orders | Fulfilled | order.fulfilled | Store |
| Canceled | order.cancelled | Store | |
| Capture Transaction | Paid | order.paid. The event order.paid is triggered when the order status is completed and captured, and the payment status is paid. | Store |
| Captured | order.updated. The event order.updated is triggered when the order is captured, completed, refunded, anonymized, or updated. | Store | |
| Refund Transaction | 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 | |
| Tax Items | Updated | cart.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 | |
Store-level events contain store_id and org_id whereas, organization-level events contain only org_id.
Authentication
- HTTP: Bearer Auth
| Security Scheme Type: | http |
|---|---|
| HTTP Authorization Scheme: | bearer |