Service Event Subscription

Link to swagger documentation

The service event subscription allows you to be notified when you have a new order, or its status has changed (e.g, return requested, canceled, etc).

IMPORTANT: your server needs to reply with http status code 200 and the following body:

{ "status":"OK"}

  1. How to subscribe to an event
  2. How to get a list of all your subscribed events
  3. How to change an event
  4. How to delete an event
  5. List of events
  6. Error Handling

1. How to subscribe to an event

You need to send a POST request to /openapi/v1/subscriptions indicating the event you would like to subscribe to.

In the body you need to specify:

  • url: string - link to valid url where you would like to receive the notifications
  • event: string containing the event. List of events here.
  • fallbackEmail: e-Mail where you would receive the notifications in case there are any problems with your url
  • isActive: boolean value

Note: If you change API Keys, you will need to subscribe to the event again.

Request example:

Endpoint: http://service-subscription-settings.sandbox.infra.metro-markets.cloud/openapi/v1/subscriptions
Body:

{
  "url": "https://webhook.site/3e0a34ed-4429-4ae8-bcf1-7b6333635da7",
  "event": "order_created",
  "fallbackEmail": "3e0a34ed-4429-4ae8-bcf1-7b6333635da7@email.webhook.site",
  "isActive": true
}

Response:

{
    "id": "c396bfde-5f5c-43a9-ac15-54111b36f31e",
    "message": "Success. Subscription for \"events.names.order_created\" event is active."
}

You can do your tests using any opensource solution like https://webhook.site/. You need to set up the response as following:

When subscribing to and / or changing an event (POST , PATCH) we will send you a notification via webhooks to ensure that the connection is stablished.
This message contains x-signature, x-client and x-timestamp in the headers and the following body:

{
  "messageId": "<uuid4>",
  "event": "test_connection",
  "payload": {
    "foo": "bar"
  }
}

2. How to get a list of all your subscribed events

You can use GET /openapi/v1/subscriptions to get a full list of all your events you are subscribed to.

Example: http://service-subscription-settings.sandbox.infra.metro-markets.cloud/openapi/v1/subscriptions
Response:

[
    {
        "id": "c396bfde-5f5c-43a9-ac15-54111b36f31e",
        "url": "https://webhook.site/3e0a34ed-4429-4ae8-bcf1-7b6333635da7",
        "event": "order_created",
        "fallbackEmail": "3e0a34ed-4429-4ae8-bcf1-7b6333635da7@email.webhook.site",
        "isActive": true
    },
    {
        "id": "da8fb1a5-0d45-4e21-9c75-632f959a8eed",
        "url": "https://webhook.site/3e0a34ed-4429-4ae8-bcf1-7b6333635da7",
        "event": "order_line_cancelled",
        "fallbackEmail": "3e0a34ed-4429-4ae8-bcf1-7b6333635da7@email.webhook.site",
        "isActive": true
    }
]

3. How to change an event

To modify a subscription event, you can send a PATCH request with the subscriptionId and indicating the new values in the body to /openapi/v1/subscriptions/{subscriptionId}.

Example of how to change the url and the e-mail.

Endpoint: http://service-subscription-settings.sandbox.infra.metro-markets.cloud/openapi/v1/subscriptions/c396bfde-5f5c-43a9-ac15-54111b36f31e

Request body:

{
  "url": "https://webhook.site/e8faca72-fe0a-49ca-ab4c-3ba967bf7c83",
  "fallbackEmail": "e8faca72-fe0a-49ca-ab4c-3ba967bf7c83@email.webhook.site",
  "isActive": true
}

*All fields are optional, but at least one needs to be in the body of the request.

Response is status code 202 with the following body:

{
    "message": "Subscription successfully updated."
}

4. How to delete an event

If you want to delete an event you need to send a DELETE request to /openapi/v1/subscriptions/{subscriptionId} indicating the subscriptionId.

Example
Request: http://service-subscription-settings.sandbox.infra.metro-markets.cloud/openapi/v1/subscriptions/c396bfde-5f5c-43a9-ac15-54111b36f31e

Response is https status code 202 with the following body:

{
    "message": "Success. Subscription for \"events.names.order_created\" event is deactivated."
}

5. List of events

Orderline created

It triggers when an order (orderline) is placed.

Event: order_created

Payload Schema

{
  "messageId": "<uniq_message_id>",
  "event": "order_created",
  "payload": {
    "orderId": "<uuid4>",
    "orderNumber": "O21-370758965005", < !--orderNumber is dynamic-->
    "organizationId": "<uuid4>",   
    "status": 1,                       < !--static value-->
    "createdAt": "<date-rfc-3339>"
  }
}

Orderline shipped

It triggers when a seller ships the orderline.
This event triggers only when the action is done in Seller Office and not via API. This is to update data on Seller’s ERP system, via API http status code 204 is provided.

Event: order_line_shipped

Payload Schema

{
  "messageId": "<uniq_message_id>",
  "event": "order_line_shipped",
  "payload": {
    "orderLineId": "<uuid4>",
    "trackings": [
      {
        "trackingId": "<string|null>",
        "carrier": "<enum:dhl|feedex|null>",
        "customCarrier": "<string|null>",
        "country": "<string>"
      }
    ],
    "statusChanged": true
  },
  "emittedAt": "<date-rfc-3339>"
}

Note: carrier is the carrier defined in our dictionary. If carrier is provided, customCarrier is null and vice versa.


Orderline canceled

It triggers when a Buyer, a METRO Markets Employee or Seller (you) cancel/s an orderline.

Event: order_line_canceled

Payload Schema

{
    "messageId": "<uniq_message_id>",
    "event": "order_line_canceled",
    "emittedAt": "<date-rfc-3339>",
    "payload": {
        "orderLineId": "<uuid4>",
        "cancellationReason": <enum:1|2>
    }
}

Note: cancellationReason can be found here. If it´s null, no reason has been given.


6. Error Handling

Authorization error

Response status code 401.
Response body:

{
  "type": "authorization",
  "title": "Authorization error",
  "status": 401,
  "detail": {
    "errors": [
      "Authentication openAPI key was not found"
    ]
  }
}

Not found error

Response status code 404.
Response body:

{
  "type": "about:blank",
  "title": "Subscription not found",
  "status": 404,
  "detail": ""
}

URL doesn’t have correct response

Response status code 412.
Response body:

{
  "type": "about:blank",
  "title": "Validation error",
  "status": 412,
  "detail": "Validation error",
  "instance": null,
  "invalidParams": [
    {
      "name": "url",
      "reason": "Server response is not valid"
    }
  ]
}

Validation error

Response status code 412.
Response body:

{
    "type": "about:blank",
    "title": "Validation error",
    "status": 412,
    "detail": "",
    "instance": null,
    "invalidParams": [
        {
            "name": "limit",
            "reason": "This value is not valid."
        },
        {
            "name": "limit",
            "reason": "This value should be greater than 0."
        }
    ]
}