Order API

In addition to the Plug & Play integration, Glopal exposes Order API that can be used to receive and process orders completed in the Glopal Checkout back into your eCommerce platform backend or other related systems, and issue refunds and manage return requests.

For your convenience, you can download the description in the OpenAPI format. Please reach out to your Glopal account manager to receive the endpoint and the API key to start your integration.

The latest API version is 2.3.2

46KB

openapi-order.yaml

Receiving orders

Endpoints

Get stream of order events

Use this endpoint to pull RECEIVED / READY / CANCELLED orders to import into your ecommerce site, OMS or other systems.

Filter for one or multiple events by passing multi-value event query parameter ("?event=order.ready&event=order.cancelled").

When pulling, record the last seen event_id in the system pulling orders and use it as after_event_id parameter in the next pull.

GET/v2/events/{store_id}

Path parameters

store_id*string

Store Identifier

Query parameters

Response

200401404

Successful response

Body

application/json

linksobject

events*array of EventListItem (object)

Request

JavaScriptCurlPython

const response = await fetch('/v2/events/{store_id}?event=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "links": {
    "next": "text",
    "current": "text",
    "previous": "text"
  },
  "events": [
    {
      "event_id": "text",
      "event_name": "order.received",
      "event_at": "2024-12-21T12:19:26.225Z",
      "order_id": "310678-936140",
      "external": {
        "order_id": "text",
        "order_number": "text"
      },
      "entity_id": "text"
    }
  ]
}

Get a specific Glopal order details

GET/v2/orders/{store_id}/{order_id}

Path parameters

store_id*string

Store Identifier

order_id*OrderId (string)

Glopal Order Identifier

Example: "310678-936140"

Pattern: ^\d+-\d+$

Response

200401404

Successful response

Body

application/json

idOrderId (string)

Example: "310678-936140"

Pattern: ^\d+-\d+$

statusOrderStatus (enum)

List of available statuses depends on the integration kind

RECEIVEDREADYACCEPTEDCOMPLETEDCANCELLED

externalOrderExternalIds (object)

currencyall of

Currency buyer used to place this order

languageall of

Language buyer used to place this order

environmentenum

livetest

customer_notestring

Order note passed from the cart

internal_notestring

Order note by Glopal

exchange_ratesobject

Currency exchange rate used to convert to order currency.

Can have up to 8 decimals.

Defined as 1 = X where following example defines 1 USD = 0.9102 EUR:

{
  currency: 'EUR',
  exchange_rates: {
    USD: {
      rate: 0.9102
    }
  }
}

created_atstring (date-time)

Creation time in UTC timezone

customerobject

billing_addressAddress (object)

shipping_addressAddress (object)

shipping_address_latin1all of

Romanized shipping address in UTF-8 encoding but restricted to Latin1 character set, if feature is enabled

glopal_summaryobject

merchant_summaryobject

summarySummary (any of)

SummaryWithTaxes (object)SummaryWithDutyAndTaxes (object)

merchant_actionsobject

documentsarray of object

cart_transferobject

Stored copy of the Checkout API cart transfer payload

total_costobject

shippingobject

discountsarray of object

itemsarray of OrderItem (object)

returnsarray of OrderReturn (object)

Request

JavaScriptCurlPython

const response = await fetch('/v2/orders/{store_id}/{order_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "310678-936140",
  "status": "RECEIVED",
  "external": {
    "order_id": "text",
    "order_number": "text"
  },
  "currency": {},
  "language": {},
  "environment": "live",
  "customer_note": "text",
  "internal_note": "text",
  "exchange_rates": {
    "USD": {
      "rate": 0.9102
    }
  },
  "created_at": "2024-12-21T12:19:26.225Z",
  "customer": {
    "first_name": "text",
    "last_name": "text",
    "email": "text",
    "email_alias": "text",
    "email_marketing_consent": "granted"
  },
  "billing_address": {
    "first_name": "text",
    "last_name": "text",
    "company": "text",
    "address1": "text",
    "postcode": "text",
    "city": "text",
    "state": "text",
    "country_code": "FR",
    "telephone": "text"
  },
  "shipping_address": {
    "first_name": "text",
    "last_name": "text",
    "company": "text",
    "address1": "text",
    "postcode": "text",
    "city": "text",
    "state": "text",
    "country_code": "FR",
    "telephone": "text"
  },
  "shipping_address_latin1": {
    "first_name": "text",
    "last_name": "text",
    "company": "text",
    "address1": "text",
    "postcode": "text",
    "city": "text",
    "state": "text",
    "country_code": "FR",
    "telephone": "text"
  },
  "glopal_summary": {
    "total": 0
  },
  "merchant_summary": {
    "total": 0
  },
  "summary": {
    "total": {
      "total": 0,
      "amount_net": 0,
      "tax_on_amount": 0,
      "glopal_tax_scheme": "euvat-ioss"
    },
    "items": {
      "total": 0,
      "amount_net": 0,
      "tax_on_amount": 0,
      "glopal_tax_scheme": "euvat-ioss"
    },
    "shipping": {
      "total": 0,
      "amount_net": 0,
      "tax_on_amount": 0,
      "glopal_tax_scheme": "euvat-ioss"
    },
    "discounts": {
      "total": 0,
      "amount_net": 0,
      "tax_on_amount": 0,
      "glopal_tax_scheme": "euvat-ioss"
    },
    "extra": {
      "total": 0,
      "amount_net": 0,
      "tax_on_amount": 0,
      "glopal_tax_scheme": "euvat-ioss"
    }
  },
  "merchant_actions": {
    "is_cancellable": false,
    "is_refundable": false
  },
  "documents": [
    {
      "name": "invoice",
      "url": "text"
    }
  ],
  "cart_transfer": {
    "checkout_id": "text",
    "items": [],
    "referrer": "text",
    "discounts": []
  },
  "total_cost": {
    "transaction_id": "text",
    "transactions": [
      {
        "transaction_id": "text",
        "from_country": "FR",
        "hub_code": "text",
        "duty_calculation_rule": "CIF",
        "tax_calculation_rule": "CIF",
        "incoterms": "DDP",
        "is_duty_deminimis_applied": false,
        "is_tax_deminimis_applied": false,
        "summary": {
          "total": {
            "total": 0,
            "amount_net": 0,
            "duty_on_amount": {},
            "tax_on_amount": {},
            "tax_on_duty": 0,
            "total_cost_transaction_id": "text",
            "glopal_tax_scheme": "euvat-ioss"
          },
          "items": {
            "total": 0,
            "amount_net": 0,
            "duty_on_amount": {},
            "tax_on_amount": {},
            "tax_on_duty": 0,
            "total_cost_transaction_id": "text",
            "glopal_tax_scheme": "euvat-ioss"
          },
          "shipping": {
            "total": 0,
            "amount_net": 0,
            "duty_on_amount": {},
            "tax_on_amount": {},
            "tax_on_duty": 0,
            "total_cost_transaction_id": "text",
            "glopal_tax_scheme": "euvat-ioss"
          },
          "discounts": {
            "total": 0,
            "amount_net": 0,
            "duty_on_amount": {},
            "tax_on_amount": {},
            "tax_on_duty": 0,
            "total_cost_transaction_id": "text",
            "glopal_tax_scheme": "euvat-ioss"
          },
          "extra": {
            "total": 0,
            "amount_net": 0,
            "duty_on_amount": {},
            "tax_on_amount": {},
            "tax_on_duty": 0,
            "total_cost_transaction_id": "text",
            "glopal_tax_scheme": "euvat-ioss"
          }
        },
        "tax_charges": [
          {
            "name": "text",
            "code": "text",
            "type": "text",
            "value": 0
          }
        ],
        "extra_charges": [
          {
            "name": "Fuel Surcharge - FR DHL",
            "code": "fuel_surcharge",
            "type": "shipping_charge",
            "value": 2.05
          }
        ]
      }
    ]
  },
  "shipping": {
    "display_name": "text",
    "service_name": "ECONOMY",
    "service_code": "text",
    "translated_name": "text",
    "tracking": [
      {
        "provider": "glopal",
        "number": "text",
        "url": "https://example.com"
      }
    ],
    "parcel_forwarding": {
      "glopal_shipping_charge": {
        "total": 0,
        "amount_net": 0,
        "tax_on_amount": 0,
        "glopal_tax_scheme": "euvat-ioss"
      },
      "merchant_shipping_charge": {
        "total": 0,
        "amount_net": 0,
        "tax_on_amount": 0,
        "glopal_tax_scheme": "euvat-ioss"
      },
      "hub_address": {
        "first_name": "text",
        "last_name": "text",
        "company": "text",
        "address1": "text",
        "postcode": "text",
        "city": "text",
        "state": "text",
        "country_code": "FR",
        "telephone": "text"
      }
    },
    "shipping_charge": {
      "total": 0,
      "amount_net": 0,
      "tax_on_amount": 0,
      "glopal_tax_scheme": "euvat-ioss"
    }
  },
  "discounts": [
    {
      "name": "text",
      "display_name": "text",
      "code": "text",
      "value_calc": {
        "merchant_amount_net": {},
        "price_adjustment_rate": 0,
        "price_adjustment_amount": 0,
        "merchant_tax_adjustment_rate": 0,
        "merchant_tax_adjustment_amount": {},
        "display_destination_tax_rate": 0,
        "display_amount": {},
        "tax_rate": 20
      },
      "value": {
        "total": 0,
        "amount_net": 0,
        "tax_on_amount": 0,
        "glopal_tax_scheme": "euvat-ioss"
      }
    }
  ],
  "items": [
    {
      "id": "text",
      "product_id": "text",
      "variant_id": "text",
      "name": "text",
      "translated_name": "text",
      "sku": "text",
      "origin_url": "https://example.com",
      "image_url": "https://example.com",
      "quantity": 0,
      "options": [
        {
          "option_id": "text",
          "value_id": "text",
          "name": "text",
          "value": "text",
          "translated_name": "text",
          "translated_value": "text"
        }
      ],
      "unit_price_calc": {
        "merchant_amount_net": {},
        "price_adjustment_rate": 0,
        "price_adjustment_amount": 0,
        "merchant_tax_adjustment_rate": 0,
        "merchant_tax_adjustment_amount": {},
        "display_destination_tax_rate": 0,
        "display_amount": {},
        "tax_rate": 20
      },
      "calculation_rule": "line_price",
      "unit_price": {
        "total": 0,
        "amount_net": 0,
        "tax_on_amount": 0,
        "glopal_tax_scheme": "euvat-ioss"
      },
      "line_price": {
        "total": 0,
        "amount_net": 0,
        "tax_on_amount": 0,
        "glopal_tax_scheme": "euvat-ioss"
      },
      "discounts": {
        "total": {
          "unit_discount": {
            "amount_net": 0
          }
        }
      },
      "total_cost": {
        "transaction_id": "text",
        "hs_code": "401519",
        "country_of_origin": {},
        "duty_rate": 16,
        "duty_deminimis": 150,
        "tax_rate": 20,
        "tax_deminimis": 0
      }
    }
  ],
  "returns": [
    {
      "id": "text",
      "created_at": "2024-12-21T12:19:26.225Z",
      "status": "REQUESTED",
      "note": "text",
      "external_id": "text",
      "shipment": {
        "tracking_number": "text",
        "carrier_name": "text",
        "label_pdf": {
          "url": "https://example.com",
          "filename": "text"
        },
        "advice_pdf": {
          "url": "https://example.com",
          "filename": "text"
        }
      },
      "items": [
        {
          "id": "text",
          "quantity": 0,
          "reason": "text"
        }
      ]
    }
  ]
}

Accept order, setting external order IDs

Observing new order from Glopal, use this endpoint to set your own order ID and order number and confirm order as accepted.

If order is already accepted having different external IDs, or if order is cancelled, request will be rejected as invalid.

It is recommended to call this endpoint only after order is marked as READY by Glopal.

Note that if this order was not previously marked as READY by Glopal, calling this endpoint will not result with the order being ACCEPTED immediately. Instead, order processing will continue on the Glopal side and order will be marked as ACCEPTED only if and after it is marked as READY by Glopal.

It is not recommended to use this endpoint together with plug'n'play integration where Glopal is attempting to insert READY orders automatically to your ecommerce backend. When using plug'n'play integration, Glopal will fetch external order IDs set by your ecommerce backend and mark order as ACCEPTED once it is inserted via plug'n'play integration.

POST/v2/orders/{store_id}/{order_id}/accept

Path parameters

store_id*string

Store Identifier

order_id*OrderId (string)

Glopal Order Identifier

Example: "310678-936140"

Pattern: ^\d+-\d+$

Body

application/json

external*AcceptOrderRequest (all of)

Response

200400401404

Successful response

Body

application/json

status*enum

ok

Request

JavaScriptCurlPython

const response = await fetch('/v2/orders/{store_id}/{order_id}/accept', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "external": {}
    }),
});
const data = await response.json();

Response

200

{
  "status": "ok"
}

Integration guide

After the purchase in the Glopal Checkout, Glopal Order API will emit different events as the order goes through order processing. To integrate with Glopal, you have to write code that will take action on specific events. You can setup a webhook to listen on events, or pull events with the /v2/events/{store_id} endpoint. We recommend the pull method for easier integration.

You can choose to import orders on RECEIVED (right after the Glopal Checkout) or READY event when Glopal marks the order as ready to be accepted by merchants. If you are just starting a new integration, we recommend starting with the READY event.

When pulling you can record the last seen event, and use this as a cursor to pull additional events.

Initial pull

curl -G \
  'https://{server}/v2/events/{store_id}' \
  -d 'event=order.ready&after_event_id=' \
  -H 'Authorization: Bearer GL.***'

Parameters event and after_event_id should be passed in the URL query (after ?)

Subsequential pulls

curl -G \
  'https://{server}/v2/events/{store_id}' \
  -d 'event=order.ready&after_event_id={event_id}' \
  -H 'Authorization: Bearer GL.***'

Parameters event and after_event_id should be passed in the URL query (after ?)

Each event returns order_id that can be used to fetch order details and then accept the order, returning your order id and number (reference) to Glopal. Glopal will use your order number to include in the order confirmation email or in the shipping & logistics part of the Glopal solution.

Note: All order amounts are presented in the transaction currency (buyer’s currency). You can choose to import the order into your system either in this or in your base currency. To import the order in the base currency, divide all amounts by the rate included in the order details response (field exchange_rates.{base}.rate).

curl \
  'https://{server}/v2/orders/{store_id}/{order_id}' \
  -H 'Authorization: Bearer GL.***'

curl -X POST \
  'https://{server}/v2/orders/{store_id}/{order_id}/accept' \
  -d '{"external": {"order_id": "42", "order_number": "ECOM-2022-42"}}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer GL.***'

Order can only be accepted once, but the call is idempotent if called with the same parameters. On success, Glopal returns HTTP 200 with {"status": "ok"} JSON response. On error, you should receive HTTP 400 with an error description in the JSON response.

If for any reason order can not be accepted, you can cancel the order, with an automatic refund.

Cancelation and refunds

Note: When cancelling the order either via API or Glopal Merchant Account user interface, Glopal will not update the order in your eCommerce backend / OMS. You can either ensure that the order is canceled inside your eCommerce backend, before canceling it through Glopal or listen / pull for the order.cancelled event via Order API.

Cancel order

Observing new order from Glopal, use this endpoint to reject the order.

Cancellation will automatically void any payment, triggering full refund or release of authorization.

You can also cancel orders that were previously accepted, assuming that order was not shipped. To refund orders that were shipped to the customer, please use the the Refund endpoint instead.

POST/v2/orders/{store_id}/{order_id}/cancel

Path parameters

store_id*string

Store Identifier

order_id*OrderId (string)

Glopal Order Identifier

Example: "310678-936140"

Pattern: ^\d+-\d+$

Body

application/json

reasonstring

Loosely codified set of reasons.

Glopal may be using different reasons, including:

• duplicate_order
• incorrect_address
• price_mismatch
• item_out_of_stock
• other

Cancellation can be initiated by either you or Glopal. Cancellations requested through this API endpoint will always be marked as initiated by the merchant.

notestring

Response

200400401404

Successful response

Body

application/json

status*enum

ok

Request

JavaScriptCurlPython

const response = await fetch('/v2/orders/{store_id}/{order_id}/cancel', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "status": "ok"
}

Calculate order refund

Calculate full or partial monetary refund.

Amount is given in the order currency.

POST/v2/orders/{store_id}/{order_id}/refund-quote

Path parameters

store_id*string

Store Identifier

order_id*OrderId (string)

Glopal Order Identifier

Example: "310678-936140"

Pattern: ^\d+-\d+$

Body

application/json

amount*Amount (number)

reason*enum

returnedlost_or_damagednot_as_describedother

notestring

Response

200400401404

Successful response

Body

application/json

quote*object

messages*array of string

Request

JavaScriptCurlPython

const response = await fetch('/v2/orders/{store_id}/{order_id}/refund-quote', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "amount": 100,
      "reason": "not_as_described"
    }),
});
const data = await response.json();

Response

200

{
  "quote": {
    "merchant_amount": 0,
    "glopal_amount": 0,
    "reason": "text",
    "note": "text"
  },
  "messages": [
    "text"
  ]
}

Refund order

Issue full or partial monetary refund.

If order is having split payment between Glopal and Merchant, request makes liability split, optionally raising a claim with Glopal if requesting that Glopal pays for the refund, fully or in part.

You can either call this endpoint directly, or use Quote Refund endpoint to pre-calculate liability.

Amounts are given in the order currency.

To cancel orders that were not shipped to the customer, please use the the Cancel endpoint instead.

POST/v2/orders/{store_id}/{order_id}/refund

Path parameters

store_id*string

Store Identifier

order_id*OrderId (string)

Glopal Order Identifier

Example: "310678-936140"

Pattern: ^\d+-\d+$

Body

application/json

merchant_amount*Amount (number)

glopal_amount*Amount (number)

reasonstring

Loosely codified set of reasons.

Glopal may be using different reasons, including:

• returned
• lost_or_damaged
• not_as_described
• other

Refund can be initiated by either you, Glopal or by lost dispute. Refunds requested through this API endpoint will always be marked as initiated by the merchant.

notestring

Response

200400401404

Successful response

Body

application/json

status*enum

ok

Request

JavaScriptCurlPython

const response = await fetch('/v2/orders/{store_id}/{order_id}/refund', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "merchant_amount": 0,
      "glopal_amount": 0
    }),
});
const data = await response.json();

Response

200

{
  "status": "ok"
}