Skip to main content

Order

The Order entity represents an order placed in your shop system.

Orders have two main states:

  • Placed: order has been accepted and paid but not shipped.
  • Fulfilled: order has been dispatched to a carrier for delivery.
    • Partially fulfilled: for orders with multiple shipments, where not all of its products are sent at the same time.

Shipment​

See Shipment for more information.

Tracking​

Order objects can have a list of trackings, that are inherently belonging to shipments.

The Tracking entity represents a shipment with a valid tracking code (a FulfilledShipment). Such shipments will receive updates from the carriers.

Operations​

Search Orders

Search for shop orders (and its trackings if any) based on filters.

Authorizations:
HTTPBasic
path Parameters
slug
required
string (Slug)

The slug identifying the shop

query Parameters
page
integer (Page) > 0
Default: 1
per_page
integer (Per Page) ( 0 .. 100 ]
Default: 30
email_id
string (Email Id)
external_id
string (External Id)
order_name
string (Order Name)
order_number
string (Order Number)
uuid
string <uuid> (Uuid)
zip_code
string (Zip Code)
order_placed_from
string <date-time> (Order Placed From)
order_placed_to
string <date-time> (Order Placed To)
shipment_updated_since
string <date-time> (Shipment Updated Since)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upsert Order

Process a shop order upsert.

Authorizations:
HTTPBasic
path Parameters
slug
required
string (Slug)

The slug identifying the shop

Request Body schema: application/json
required
id
required
string (Id)

Order reference whose type is defined by the id_type field

id_type
string (OrderReferenceType)
Default: "order_number"
Enum: "uuid" "external_id" "order_name" "order_number"

Type of order identifier that is passed in the reference field

object (Order)

Order information (will perform an upsert if provided)

required
Array of objects (Trackings)

Tracking information relevant to the order (order must exist already if it is not provided)

Responses

Request samples

Content type
application/json
{
  • "id": "11334422",
  • "id_type": "order_number",
  • "order": {
    },
  • "trackings": [
    ]
}

Response samples

Content type
application/json
null

Place Order

Process a shop order placement.

Authorizations:
HTTPBasic
path Parameters
slug
required
string (Slug)

The slug identifying the shop

Request Body schema: application/json
required
order_number
required
string (Order Number)

Opinionated numeric identification of the order

order_name
string (Order Name)

Opinionated name of the order

order_placed_at
string <date-time> (Order Placed At)

Date the order was placed. Will take current time if not provided

total_order_price
number (Total Order Price)

Total price of the order

shipping_price
number (Shipping Price)

Total shipping price of the order

sub_total_price
number (Sub Total Price)

Subtotal price of items before shipping and discounts

discount_price
number (Discount Price)
Default: 0

Total price of all the accumulated discounts

Array of objects (Products)
Default: []

Line items for the order

Array of objects (Discounts)
Default: []

Discounts applied to the order

email_id
string (Email Id)

Email address of the customer

required
object (Address)

Shipment delivery address

currency
string (Currency)
Default: "EUR"

ISO 4217 currency code (default to 'EUR')

segments
Array of strings (Segments)

The segments to which the user of the order belongs

weight
number (Weight)

Total weight of the order in grams

external_customer_id
string (External Customer Id)

External ID of the customer who purchased the order

order_status_url
string (Order Status Url)

URL to the order status page as given by the shop provider

external_id
required
string (External Id)

External identifier of the order as defined by the merchant shop system (e.g. shopify's order id)

object (Preferred Delivery Date)

Preferred delivery date for the order

user_agent
string (User Agent)

User agent of the customer

order_analytics
object (Order Analytics)
Default: {}

Analytics information related to the order. This information is not used for any computation, but can be used to track the order in the merchant's analytics system.

expected_number_of_shipments
integer (Expected Number Of Shipments) <= 100
Default: 1

Expected number of shipments for the order (defaults to 1)

Responses

Request samples

Content type
application/json
{
  • "order_number": "1234",
  • "order_name": "IXF1234",
  • "order_placed_at": "2023-03-17T09:51:41+00:00",
  • "total_order_price": 29.99,
  • "shipping_price": 4.99,
  • "sub_total_price": 40,
  • "discount_price": 4.99,
  • "products": [
    ],
  • "discounts": [
    ],
  • "email_id": "[email protected]",
  • "address": {
    },
  • "currency": "EUR",
  • "segments": [
    ],
  • "weight": 1000,
  • "external_customer_id": "1234067358984",
  • "order_status_url": "https://shop.gokarla.io/1234067358984/orders/aabbcc/authenticate?key=secret",
  • "external_id": "2205783916624",
  • "preferred_delivery_date": {
    },
  • "user_agent": [
    ],
  • "order_analytics": { },
  • "expected_number_of_shipments": 1
}

Response samples

Content type
application/json
null

Update Order

Process a shop order update.

Authorizations:
HTTPBasic
path Parameters
slug
required
string (Slug)

The slug identifying the shop

order_id
required
string <uuid> (Order Id)

The id given by Karla identifying the order

Request Body schema: application/json
required
object (Address)

Shipment delivery address (skips update if undefined).

expected_number_of_shipments
integer (Expected Number Of Shipments) <= 100

Expected number of shipments for the order (skips update if undefined).

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "expected_number_of_shipments": 1
}

Response samples

Content type
application/json
{
  • "order_number": "1234",
  • "order_name": "IXF1234",
  • "order_placed_at": "2023-03-17T09:51:41+00:00",
  • "total_order_price": 29.99,
  • "shipping_price": 4.99,
  • "sub_total_price": 40,
  • "discount_price": 4.99,
  • "products": [
    ],
  • "discounts": [
    ],
  • "email_id": "[email protected]",
  • "address": {
    },
  • "currency": "EUR",
  • "segments": [
    ],
  • "weight": 1000,
  • "external_customer_id": "1234067358984",
  • "order_status_url": "https://shop.gokarla.io/1234067358984/orders/aabbcc/authenticate?key=secret",
  • "merchant_slug": "string",
  • "external_id": "string",
  • "uuid": "b4fadda9-61f4-4041-94d2-7a01ee0082b4",
  • "trackings": [
    ]
}

Update Order Shipment

Process a shop order shipment update.

Authorizations:
HTTPBasic
path Parameters
slug
required
string (Slug)

The slug identifying the shop

order_id
required
string <uuid> (Order Id)

The id given by Karla identifying the order

shipment_id
required
string <uuid> (Shipment Id)

The id given by Karla identifying the tracking from the order

Request Body schema: application/json
required
tracking_url
string (Tracking Url)

The tracking URL as it comes from the carrier.

Array of objects (Products)

Line items involved in the delivery. Give an empty list to remove all products from the shipment.Any list provided will override the current products in the shipment (there is no merge). Will be skipped from update if not given

Responses

Request samples

Content type
application/json
{
  • "tracking_url": "string",
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "events": [
    ],
  • "estimated_arrival": {
    },
  • "carrier": {
    },
  • "flag": "normal",
  • "pickup": {
    },
  • "products": [ ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "merchant_slug": "string",
  • "shop_slug": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "order_number": "string"
}

Fulfill Orders

Process a shop order fulfillment in bulk (via shop slug).

Authorizations:
HTTPBasic
path Parameters
slug
required
string (Slug)

The slug identifying the shop

Request Body schema: application/json
required
Array
id
required
string (Id)

Order reference whose type is defined by the id_type field

id_type
string (OrderReferenceType)
Default: "order_number"
Enum: "uuid" "external_id" "order_name" "order_number"

Type of order identifier that is passed in the reference field

object (Order)

Order information (will perform an upsert if provided)

required
Array of objects (Trackings)

Tracking information relevant to the order (order must exist already if it is not provided)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
null

API Reference​