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
:::note Store-level events contain `store_id` and `org_id` whereas, organization-level events contain only `org_id`. ::: security: - bearerAuth: [ ] servers: - url: https://euwest.api.elasticpath.com description: US West Cluster - url: https://useast.api.elasticpath.com description: US East Cluster tags: - name: Integrations description: Setting up and managing integrations. paths: /integrations: get: summary: List integrations description: Returns a list of all integrations created by the store. tags: - Integrations operationId: ListIntegrations responses: 200: description: Success. All integrations are returned. content: application/json: schema: type: object properties: data: type: array items: allOf: - $ref: '#/components/schemas/Integration' - $ref: '#/components/schemas/Links' - $ref: '#/components/schemas/Meta' links: $ref: '#/components/schemas/Links' meta: $ref: '#/components/schemas/Meta' 500: $ref: '#/components/responses/InternalServerError' post: summary: Create an integration description: Create an integration. tags: - Integrations operationId: CreateIntegration requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/IntegrationCreate' responses: 200: description: Success. Integration created. content: application/json: schema: type: object properties: data: allOf: - $ref: '#/components/schemas/Integration' - $ref: '#/components/schemas/Links' - $ref: '#/components/schemas/Meta' 422: $ref: '#/components/responses/ValidationError' 500: $ref: '#/components/responses/InternalServerError' /integrations/{integration_uuid}: get: parameters: - $ref: "#/components/parameters/IntegrationUUID" summary: Get an integration description: Returns the integration for the given UUID. tags: - Integrations operationId: GetIntegration responses: 200: description: Success. An integration is returned. content: application/json: schema: type: object properties: data: allOf: - $ref: '#/components/schemas/Integration' - $ref: '#/components/schemas/Links' - $ref: '#/components/schemas/Meta' 404: $ref: '#/components/responses/NotFoundError' 500: $ref: '#/components/responses/InternalServerError' put: parameters: - $ref: "#/components/parameters/IntegrationUUID" summary: Update an integration description: Updates the Integration for the given UUID. Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the integration is not updated. tags: - Integrations operationId: UpdateIntegration requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/IntegrationUpdate' responses: 200: description: Success. All integrations are returned content: application/json: schema: type: object properties: data: allOf: - $ref: '#/components/schemas/Integration' - $ref: '#/components/schemas/Links' - $ref: '#/components/schemas/Meta' links: $ref: '#/components/schemas/Links' meta: $ref: '#/components/schemas/Meta' 404: $ref: '#/components/responses/NotFoundError' 422: $ref: '#/components/responses/ValidationError' 500: $ref: '#/components/responses/InternalServerError' delete: parameters: - $ref: "#/components/parameters/IntegrationUUID" summary: Delete an integration description: Deletes the Integration for the given UUID tags: - Integrations operationId: DeleteIntegration responses: 200: description: Integration was successfully deleted 500: $ref: '#/components/responses/InternalServerError' /integrations/logs: get: summary: List logs for all integrations for the store description: Returns all integration logs for the store. tags: - Integrations operationId: ListStoreLogs responses: 200: description: Success. Returns a list of integration logs. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/IntegrationLog' meta: $ref: '#/components/schemas/PaginationMeta' results: $ref: '#/components/schemas/Results' 500: $ref: '#/components/responses/InternalServerError' /integrations/{integration_uuid}/logs: parameters: - $ref: "#/components/parameters/IntegrationUUID" get: summary: List logs for integration description: Returns the logs for the given integration UUID. tags: - Integrations operationId: ListIntegrationLogs responses: 200: description: Success. Returns a list of integration logs. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/IntegrationLog' meta: $ref: '#/components/schemas/PaginationMeta' results: $ref: '#/components/schemas/Results' 404: $ref: '#/components/responses/NotFoundError' 500: $ref: '#/components/responses/InternalServerError' /integrations/{integration_uuid}/jobs: parameters: - $ref: "#/components/parameters/IntegrationUUID" get: summary: List jobs for integration description: Returns the jobs for the given integration UUID. tags: - Integrations operationId: ListIntegrationJobs responses: 200: description: Success. All integrations are returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/IntegrationJob' 404: $ref: '#/components/responses/NotFoundError' 500: $ref: '#/components/responses/InternalServerError' /integrations/{integration_uuid}/jobs/{job_uuid}/logs: parameters: - $ref: "#/components/parameters/IntegrationUUID" - $ref: "#/components/parameters/JobUUID" get: summary: List logs for the job description: Returns the integration logs for the given integration and job UUID. tags: - Integrations operationId: ListJobLogs responses: 200: description: Success. Returns a list of integration logs. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/IntegrationLog' meta: $ref: '#/components/schemas/PaginationMeta' results: $ref: '#/components/schemas/Results' 404: $ref: '#/components/responses/NotFoundError' 500: $ref: '#/components/responses/InternalServerError' components: securitySchemes: bearerAuth: type: http scheme: bearer parameters: IntegrationUUID: name: integration_uuid in: path description: The unique identifier of the integration. required: true schema: type: string JobUUID: name: job_uuid in: path description: The unique identifier of the integration job. required: true schema: type: string responses: ValidationError: description: Bad request. The request failed validation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing-name: value: errors: - title: Validation Error status: 400 detail: 'Your request was invalid' InternalServerError: description: Internal server error. There was a system failure in the platform. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal-server-error: value: errors: - title: Internal Server Error status: 500 NotFoundError: description: Not found. The requested entity does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not-found: value: errors: - title: Not Found status: 404 detail: The resource could not be found schemas: IntegrationCreate: required: - type - observers - integration_type - name - configuration properties: type: description: The type represents the object being returned. Always `integration`. type: string example: integration enum: - integration default: integration name: type: string example: Order shipping notification description: The name of the integration. description: type: string example: Send a shipping notification via email with discount code description: A description of what the integration is for. enabled: type: boolean example: true description: Whether the integration is enabled. integration_type: type: string description: Specifies how the event is delivered. The options are `webhook`, `aws-sqs`, or `stomp`. example: webhook enum: - webhook - aws_sqs - stomp default: webhook observes: description: The list of events you want to observe. See [**Observable Events**](#observable-events). type: array items: type: string configuration: description: The content of the configuration object depends on the value of `integration_type`. type: object oneOf: - $ref: "#/components/schemas/AWSSQSConfigurationObject" - $ref: "#/components/schemas/WebhookConfigurationObject" - $ref: "#/components/schemas/STOMPConfigurationObject" IntegrationUpdate: required: - type properties: type: description: The type represents the object being returned. Always `integration`. type: string example: integration enum: - integration default: integration name: type: string example: Order shipping notification description: The name of the integration. description: type: string example: Send a shipping notification via email with discount code description: A description of what the integration is for. enabled: type: boolean example: true description: Whether the integration is enabled. integration_type: type: string example: webhook enum: - webhook - aws_sqs - stomp default: webhook observes: type: array description: The list of events you want to observe. See [**Observable Events**](#observable-events). items: type: string configuration: description: The content of the configuration object depends on the value of `integration_type`. type: object oneOf: - $ref: "#/components/schemas/AWSSQSConfigurationObject" - $ref: "#/components/schemas/WebhookConfigurationObject" - $ref: "#/components/schemas/STOMPConfigurationObject" Integration: properties: id: description: The unique identifier of the integration. type: string example: 2da46671-b4c2-44ac-b133-d1221aafc77b type: description: The type represents the object being returned. Always `integration`. type: string example: integration enum: - integration default: integration name: type: string example: Order shipping notification description: The name of the integration. description: type: string example: Send a shipping notification via email with discount code description: A description of what the integration is for. enabled: type: boolean example: true description: Whether the integration is enabled. integration_type: type: string example: webhook description: Specifies how the event is delivered. The options are `webhook`, `aws-sqs`, or `stomp`. enum: - webhook - aws_sqs - stomp default: webhook observes: description: The list of events you want to observe. See [**Observable Events**](#observable-events). type: array items: type: string configuration: type: object oneOf: - $ref: "#/components/schemas/AWSSQSConfigurationObject" - $ref: "#/components/schemas/WebhookConfigurationObject" - $ref: "#/components/schemas/STOMPConfigurationObject" IntegrationLog: description: As integrations can fail over time, Commerce provides the ability to browse all logs for your integrations. properties: id: description: A unique identifier of an integration whose logs you want to view. type: string example: ac8bb58e-2b9b-4ccf-9dd2-ecdf50417849 type: description: This represents the type of resource object being returned. Always `integration`. type: string example: integration enum: - integration default: integration succeeded: type: boolean example: true description: Whether the integration was successful. attempt: type: integer example: 1 description: The number of attempts made to process the integration. body: type: string example: Not Found description: The response returned from the integration. status_code: type: integer example: 404 description: The status code returned from the integration. error_detail: type: string example: Received a status code outside of 2xx range - treating webhook as a fail description: The reason why the integration failed. relationships: description: Relationships are established between different integration entities. For example, a log and an integration job are related to an integration. type: object properties: integration: type: object properties: data: type: object properties: id: type: string description: The ID of the integration processed. example: ff8634a8-a89e-4eac-baab-9b7b8c4f8720 type: type: string description: This represents the resource type of the object being returned. Always `integration`. example: integration job: type: object properties: data: type: object properties: id: type: string description: The ID of the integration job processed. example: ff8634a8-a89e-4eac-baab-9b7b8c4f8720 type: type: string description: This represents the resource type of the object being returned. Always `integration-job`. example: job IntegrationJob: properties: id: description: The ID of the integration job processed. type: string example: 8848646b-2745-469e-8cc1-ee3b04738f8f type: type: string description: This represents the type of resource object being returned. Always `integration-job`. enum: - integration-job example: integration-job WebhookConfigurationObject: required: - url properties: url: type: string example: https://yourwebsite.com/order-created-notification description: A required URL that the integration fires. secret_key: type: string example: secret_key_to_validate_on_your_endpoint description: An optional header. Useful to authenticate the response came from Elastic Path. This is sent as `X-MOLTIN-SECRET-KEY`. AWSSQSConfigurationObject: required: - url - aws_access_key_id - aws_secret_access_key - region properties: url: type: string example: https://sqs.eu-west-1.amazonaws.com/123456789/epcc-external-queue description: The required SQS queue URL. aws_access_key_id: type: string example: "****************JIMB" description: The required AWS access key ID. aws_secret_access_key: type: string example: "************************************HK4o" description: The required AWS secret key ID. region: type: string example: eu-west-1 description: The required AWS region. STOMPConfigurationObject: required: - url properties: username: type: string example: epcc-integration-1 description: The username used to authenticate against a STOMP server. password: type: string example: "****************************CDKn" description: The password used to authenticate against a STOMP server. destination: type: string example: /queue/epcc-integrations.order-created description: The destination in the messaging queuing system. addresses: type: array items: type: string example: - stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-2.mq.us-west-2.amazonaws.com:61614 - stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-1.mq.us-west-2.amazonaws.com:61614 description: The addresses that correspond with the destination name. Results: description: The results for this response for the entire collection. type: object properties: total: description: The total number of records for this response for the entire collection. type: integer example: 1 Meta: type: object properties: meta: type: object properties: timestamps: $ref: "#/components/schemas/Timestamps" Links: type: object properties: links: description: Links are used to allow you to move between requests. type: object properties: self: description: Single entities use a self parameter with a link to that specific resource. $ref: '#/components/schemas/LinkURI' LinkURI: type: string format: uri example: ?page[offset]=0&page[limit]=25 ErrorResponse: required: - errors properties: errors: type: array items: $ref: '#/components/schemas/ErrorBody' ErrorBody: required: - title properties: status: type: integer format: int description: The HTTP response code of the error. example: 500 title: type: string description: A brief summary of the error. example: Internal server error detail: type: string description: Optional additional detail about the error. example: An internal error has occurred. Timestamps: description: The date and time a transaction is created. properties: created_at: description: The date and time an integration is updated. type: string format: date-time example: '2017-07-21T17:32:28Z' updated_at: description: The date and time an integration is updated. type: string format: date-time example: '2017-07-21T17:32:28Z' PaginationMeta: type: object properties: limit: description: The maximum number of records per page for a response. You can set this value up to 100. type: integer example: 100 offset: description: The current offset by number of records, not pages. Offset is zero-based. type: integer example: 0 current: description: The current page. type: integer example: 1 total: description: The total page count. type: integer example: 1