Skip to main content
Version: 1.0.0

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.

note

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

Integration Types

Commerce supports the following integration types:

  • Using webhooks, 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, 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.
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.

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.

AttributeTypeDescription
idstringA unique ID for this event.
integrationobjectThe events integration_type being fired.
triggered_bystringThe observable events that triggered this event.
attemptintegerThe number of attempts to deliver this event.
resourcesstringThe resources affected by this event. This field is now deprecated. Please use payload instead.
payloadobjectThe 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 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:

AttributeTypeDescription
idstringA unique ID for this event.
integrationidstringThe ID of the integration being fired.
typestringThe observable event that triggered this event.
dataobjectThe 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/ResourceActionObservable KeyStore/Organization
AddressCreatedaddress.createdStore
Updatedaddress.updatedStore
Deletedaddress.deletedStore
AccountCreatedaccount.createdStore
Updatedaccount.updatedStore
Deletedaccount.deletedStore
Account MemberCreatedaccount-member.createdStore
Updatedaccount-member.updatedStore
Deletedaccount-member.deletedStore
Account MembershipCreatedaccount-membership.createdStore
Updatedaccount-membership.updatedStore
Deletedaccount-membership.deletedStore
CartsUpdatedcart.updatedStore
Deletedcart.deletedStore
CurrencyCreatedcurrency.createdStore
Updatedcurrency.updatedStore
Deletedcurrency.deletedStore
CustomerCreatedcustomer.createdStore
Updatedcustomer.updatedStore
Deletedcustomer.deletedStore
Custom API EntriesCreatedcustomAPIEntryType.createdStore
UpdatedcustomAPIEntryType.updatedStore
DeletedcustomAPIEntryType.deletedStore
FileCreatedfile.createdStore
Deletedfile.deletedStore
Integration (events)Createdintegration.createdStore, Organization
Updatedintegration.updatedStore, Organization
Deletedintegration.deletedStore, Organization
One-Time Password Token RequestCreatedone-time-password-token-request.createdStore
Order Events
CheckoutCreatedorder.createdStore
PaymentsUpdatedorder.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
Authorizedorder.authorizedStore
OrdersFulfilledorder.fulfilledStore
Canceledorder.cancelledStore
Capture TransactionPaidorder.paid. The event order.paid is triggered when the order status is completed and captured, and the payment status is paid.Store
Capturedorder.updated. The event order.updated is triggered when the order is captured, completed, refunded, anonymized, or updated.Store
Refund TransactionRefundedorder.refundedStore
Payment GatewayUpdatedpayment-gateway.updatedStore
Catalog releasesCreatedcatalog-release.createdStore, Organization
Updatedcatalog-release.updatedStore, Organization
Deletedcatalog-release.deletedStore, Organization
Catalog rulesCreatedcatalog-rule.createdStore
Updatedcatalog-rule.updatedStore
Deletedcatalog-rule.deletedStore
SettingsCreatedsettings.createdStore
Updatedsettings.updatedStore
Stock TransactionCreatedstock-transaction.createdStore
TransactionCreatedtransaction.createdStore
Updatedtransaction.updatedStore
Tax ItemsUpdatedcart.updatedStore
SubscriptionsYou 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 InfoCreateduser-authentication-info.createdStore
Updateduser-authentication-info.updatedStore
Deleteduser-authentication-info.deletedStore
note

Store-level events contain store_id and org_id whereas, organization-level events contain only org_id.

Authentication

Security Scheme Type:http
HTTP Authorization Scheme:bearer