Swagger explorer

An example request to retrieve a customer object

get https://backoffice-url/customer?email={email}

Retrieve a single customer object from your backoffice accompanied by their orders, subscriptions, payments, etc..
Customer is identified by the URL parameter {email}.

Note: This URL will be called every time a new ticket arrives in the helpdesk.

A few important notes

The RESPONSE EXAMPLE to the right is just an example of how you can structure your backofice API that will be consumed by the Gorgias Helpdesk.
It can be used as a blueprint to create one yourself and also defines some common things that you'll need.

On the high level the structure that we're interested in looks like:

    Customer
        Orders
            Order1
                OrderItems
                    OrderItem1
                    OrderItem2
                    ...
            Order2
            ...
        Refunds
        Payments
        Subscriptions
        ...

Metadata objects (the `meta` field)

The metadata objects (__meta__ fields in the schema) are a special because they define additional information (metadata) of your objects.

Note: Use of `meta` is entirely optional but it could be incredibly useful for support agents.

Common use cases of metadata:

A link to your customer object in your backoffice so that the agent can easily access it in your own system.
Sort order for the list of orders. Say you want to sort by creation date of the order in descending order.

There are 2 types of meta objects:

Single object metadata (search for MetaSchema for more info) - these are used for individual objects (Ex: Customer, Order)
List object metadata (search for MetaListSchema for more info) - these are used for lists of objects (Ex: Orders, Subscriptions, etc..)

Response Example

{
  "__meta__": {
    "excludeFields": [
      "field-we-dont-need",
      "some-field"
    ],
    "object": "customer",
    "operations": [
      {
        "method": "PUT",
        "type": "update",
        "url": "https://backoffice-url/customer/{this.id}"
      }
    ],
    "url": "https://backoffice-url/customer/{this.customerId}"
  },
  "active": true,
  "email": "marie@curie.org",
  "id": 123,
  "name": "Marie Curie",
  "orders": {
    "__meta__": {
      "displayLimit": 3,
      "object": "list",
      "sortDir": "asc",
      "sortKey": "createdDate",
      "url": "https://backoffice-url/customer/{this.customerId}/list/"
    },
    "data": [
      {
        "__meta__": {
          "excludeFields": [
            "field-we-dont-need",
            "some-field"
          ],
          "object": "order",
          "operations": [
            {
              "method": "PUT",
              "type": "update",
              "url": "https://backoffice-url/customer/{this.id}"
            }
          ],
          "url": "https://backoffice-url/customer/{parent.customerId}/orders/{this.id}"
        },
        "createdDate": "2016-03-16T11:12:09.409Z",
        "currency": "USD",
        "deliveryDate": "2016-03-16T11:12:09.409Z",
        "id": 123,
        "items": {
          "__meta__": {
            "displayLimit": 3,
            "object": "list",
            "sortDir": "asc",
            "sortKey": "createdDate",
            "url": "https://backoffice-url/customer/{this.customerId}/list/"
          },
          "data": [
            {
              "__meta__": {
                "excludeFields": [
                  "field-we-dont-need",
                  "some-field"
                ],
                "object": "customer",
                "operations": [
                  {
                    "method": "PUT",
                    "type": "update",
                    "url": "https://backoffice-url/customer/{this.id}"
                  }
                ],
                "url": "https://backoffice-url/customer/{this.customerId}"
              },
              "id": 123,
              "name": "Eggs",
              "price": 120,
              "quantity": 1,
              "sku": "eggs-12"
            }
          ]
        },
        "merchant": {
          "__meta__": {
            "excludeFields": [
              "field-we-dont-need",
              "some-field"
            ],
            "object": "customer",
            "operations": [
              {
                "method": "PUT",
                "type": "update",
                "url": "https://backoffice-url/customer/{this.id}"
              }
            ],
            "url": "https://backoffice-url/customer/{this.customerId}"
          },
          "address": {
            "city": "New York City",
            "state": "NY",
            "street": "1407 Broadway",
            "zipcode": "10018"
          },
          "createdDate": "2016-03-16T11:12:09.410Z",
          "id": 123,
          "items": {
            "__meta__": {
              "displayLimit": 3,
              "object": "list",
              "sortDir": "asc",
              "sortKey": "createdDate",
              "url": "https://backoffice-url/customer/{this.customerId}/list/"
            },
            "data": [
              {
                "__meta__": {
                  "excludeFields": [
                    "field-we-dont-need",
                    "some-field"
                  ],
                  "object": "customer",
                  "operations": [
                    {
                      "method": "PUT",
                      "type": "update",
                      "url": "https://backoffice-url/customer/{this.id}"
                    }
                  ],
                  "url": "https://backoffice-url/customer/{this.customerId}"
                },
                "id": 123,
                "name": "Eggs",
                "price": 120,
                "quantity": 1,
                "sku": "eggs-12"
              }
            ]
          },
          "name": "Cafe Kebab",
          "phone": "+40 054 5454 488"
        },
        "total": 10.23,
        "trackingURL": "https://your-tracking/orderId={{this.id}}"
      }
    ]
  },
  "payments": {
    "__meta__": {
      "displayLimit": 3,
      "object": "list",
      "sortDir": "asc",
      "sortKey": "createdDate",
      "url": "https://backoffice-url/customer/{this.customerId}/list/"
    },
    "data": [
      {
        "__meta__": {
          "excludeFields": [
            "field-we-dont-need",
            "some-field"
          ],
          "object": "customer",
          "operations": [
            {
              "method": "PUT",
              "type": "update",
              "url": "https://backoffice-url/customer/{this.id}"
            }
          ],
          "url": "https://backoffice-url/customer/{this.customerId}"
        },
        "amount": 200,
        "currency": "USD",
        "id": 123,
        "orderId": 102
      }
    ]
  },
  "refunds": {
    "__meta__": {
      "displayLimit": 3,
      "object": "list",
      "sortDir": "asc",
      "sortKey": "createdDate",
      "url": "https://backoffice-url/customer/{this.customerId}/list/"
    },
    "data": [
      {
        "__meta__": {
          "excludeFields": [
            "field-we-dont-need",
            "some-field"
          ],
          "object": "customer",
          "operations": [
            {
              "method": "PUT",
              "type": "update",
              "url": "https://backoffice-url/customer/{this.id}"
            }
          ],
          "url": "https://backoffice-url/customer/{this.customerId}"
        }
      }
    ]
  },
  "registrationDate": "2016-03-16T11:12:09.413Z",
  "subscriptions": {
    "__meta__": {
      "displayLimit": 3,
      "object": "list",
      "sortDir": "asc",
      "sortKey": "createdDate",
      "url": "https://backoffice-url/customer/{this.customerId}/list/"
    },
    "data": [
      {
        "__meta__": {
          "excludeFields": [
            "field-we-dont-need",
            "some-field"
          ],
          "object": "customer",
          "operations": [
            {
              "method": "PUT",
              "type": "update",
              "url": "https://backoffice-url/customer/{this.id}"
            }
          ],
          "url": "https://backoffice-url/customer/{this.customerId}"
        }
      }
    ]
  }
}

Response Objects

{} Customer

__meta__MetaSchema(optional)

activeboolean(optional)Bool fields are supported of course

emailstring(optional)Email of the customer

idinteger(optional)Your customer id. It's not required to be {id}. It can be {customerId} or {userId} - whatever your DB looks like.

namestring(optional)Name of the customer

ordersOrders(optional)

paymentsPayments(optional)

refundsRefunds(optional)

registrationDatestring(optional)Datetime data types are detected automatically if the use the ISO (https://en.wikipedia.org/wiki/ISO_8601) format. NOTE: provides dates in UTC for best experience.

subscriptionsSubscriptions(optional)

{} MetaSchema

excludeFieldsarray[string](optional)What fields should be excluded from display

objectstringShows what type of object we have. This is useful later on for the helpdesk stats, automations, etc..

Can be customer, order, orderItem, refund, subscription or payment

operationsarray[Operation](optional)

urlstring(optional)Where we can view this object in the backoffice

{} Orders

__meta__MetaListSchema(optional)

dataarray[Order](optional)

{} Payments

__meta__MetaListSchema(optional)

dataarray[Payment](optional)

{} Refunds

__meta__MetaListSchema(optional)

dataarray[Refund](optional)

{} Subscriptions

__meta__MetaListSchema(optional)

dataarray[Subscription](optional)

{} Operation

methodstring(optional)HTTP Method used to send the request

Can be PUT, GET or POST

typestring

Can be update, create or delete

urlstring(optional)The URL of the operation

{} MetaListSchema

displayLimitinteger(optional)How many items should be shown by default

objectstringThis is a list object so we should specify it's a list

sortDirstring(optional)

Can be asc or desc

sortKeystring(optional)What key should be used to sort this list

urlstring(optional)The url of this object

{} Order

__meta__Inline Model 1(optional)

createdDatestring(optional)

currencystring(optional)

deliveryDatestring(optional)

idinteger(optional)Order id i

itemsOrderItems(optional)

merchantMerchant(optional)This is a merchant

totalnumber(optional)Float JSON values are also supported

trackingURLstring(optional)

{} Payment

__meta__Inline Model 2(optional)

amountnumber(optional)

currencystring(optional)

idinteger(optional)

orderIdinteger(optional)

{} Refund

__meta__Inline Model 3(optional)

{} Subscription

__meta__Inline Model 4(optional)

{} Inline Model 1

excludeFieldsarray[string](optional)What fields should be excluded from display

objectstring

operationsarray[Operation](optional)

urlstring(optional)

{} OrderItems

__meta__MetaListSchema(optional)

dataarray[OrderItem](optional)

{} Merchant

__meta__Inline Model 5(optional)

addressAddress(optional)

createdDatestring(optional)

idinteger(optional)

itemsOrderItems(optional)

namestring(optional)

phonestring(optional)

{} Inline Model 2

excludeFieldsarray[string](optional)What fields should be excluded from display

objectstringShows what type of object we have. This is useful later on for the helpdesk stats, automations, etc..

Can be customer, order, orderItem, refund, subscription or payment

operationsarray[Operation](optional)

urlstring(optional)Where we can view this object in the backoffice

{} Inline Model 3

excludeFieldsarray[string](optional)What fields should be excluded from display

objectstringShows what type of object we have. This is useful later on for the helpdesk stats, automations, etc..

Can be customer, order, orderItem, refund, subscription or payment

operationsarray[Operation](optional)

urlstring(optional)Where we can view this object in the backoffice

{} Inline Model 4

excludeFieldsarray[string](optional)What fields should be excluded from display

objectstringShows what type of object we have. This is useful later on for the helpdesk stats, automations, etc..

Can be customer, order, orderItem, refund, subscription or payment

operationsarray[Operation](optional)

urlstring(optional)Where we can view this object in the backoffice

{} OrderItem

__meta__Inline Model 6(optional)

idinteger(optional)

namestring(optional)

priceinteger(optional)

quantityinteger(optional)

skustring(optional)

{} Inline Model 5

excludeFieldsarray[string](optional)What fields should be excluded from display

objectstringShows what type of object we have. This is useful later on for the helpdesk stats, automations, etc..

Can be customer, order, orderItem, refund, subscription or payment

operationsarray[Operation](optional)

urlstring(optional)Where we can view this object in the backoffice

{} Address

citystring(optional)

statestring(optional)

streetstring(optional)

zipcodestring(optional)

{} Inline Model 6

excludeFieldsarray[string](optional)What fields should be excluded from display

objectstringShows what type of object we have. This is useful later on for the helpdesk stats, automations, etc..

Can be customer, order, orderItem, refund, subscription or payment

operationsarray[Operation](optional)

urlstring(optional)Where we can view this object in the backoffice

An example request to retrieve a customer object

get https://backoffice-url/customer?email={email}

Note: This URL will be called every time a new ticket arrives in the helpdesk.

A few important notes

Metadata objects (the __meta__ field)

Note: Use of __meta__ is entirely optional but it could be incredibly useful for support agents.

Example Parameters

Response Example

Response Objects

Metadata objects (the `meta` field)

Note: Use of `meta` is entirely optional but it could be incredibly useful for support agents.