General

The Order integration service has two main functions:

  • It allows a brand to retrieve their orders from the FashionTrade platform, optionally filtering on a start and end date, and status

  • Maintain metadata

    • Attach metadata on a brand level

    • Attach metadata on an order level

    • Attach metadata on an order line level

Important
metadata is always a single instance. This means that for example an order has one metadata record.

The Order integration service currently supports one resource:

  • Order resource

Order resource

An order is composed of metadata including an order number, the retailer name, an expected delivery date, the delivery address, status of the order, the total price, the retailer’s vat number, invoice address and date the order was placed. An order also contains a collection of order lines, which specify the product details, quantity and price.

There are several options to retrieve the orders for a brand:

  • Get all orders

  • Get all orders, paginated

  • Get orders specifying a from and do date

  • Filter orders by status

  • Any combination of the above

More information can be found in the API description.

Brand metadata

Here we can store meta data on a brand level, meaning that the meta data is not tied to a specific order or order line.

Possible use cases:

  • Store the data of the last order that was processed.

Order metadata

Here we can store meta data on an order level.

Possible use cases:

  • Store reference(s) to a brand specific ERP system.

Order line metadata

Here we can store meta data on an order line level.

Possible use cases:

  • Store reference(s) to a brand specific ERP system, for example when a single order line is split into two different order lines.

Overview

Title

Usage


curl http://foo.bar.com

bla bla

This service is responsible for handling brand order-related operations and queries

URI scheme

Host : api.fashiontrade.com
BasePath : /order-integration
Schemes : HTTPS

Tags

  • brand-order-rules

  • order line metadata

  • order metadata

  • orders

Definitions

Address

Name Schema

address_line1
required

string

address_line2
optional

string

city
required

string

country
required

string

zipcode
required

string

AttachedMessage

Information about a message sent with the order

Name Description Schema

sender
required

Message’s sender

text
required

Message’s text

string

timestamp
required

ISO 8601 representation of when the message was sent

string

AttachedMessageSender

Information about the sender of the message

Name Description Schema

organization
required

Sender organization

user
optional

Sender user

AttachedMessageSenderOrganization

Information about the organization that sent the message

Name Description Schema

name
optional

Organization’s name

string

type
required

Organization’s type

enum (BRAND, RETAILER)

AttachedMessageSenderUser

Information about the user who sent the message

Name Description Schema

email
required

User’s email address

string

name
required

User’s full name

string

BrandOrderLocationRules

Definition of brand-specific rules whether an order can pass through to the integration depending on which locations IDs are set

Name Description Schema

is_delivery_id_optional
required

Defines whether a single external delivery address ID must be set

boolean

is_invoice_id_optional
required

Defines whether a single external invoice address ID must be set

boolean

is_shop_id_optional
required

Defines whether a single external shop ID must be set

boolean

DateRange

Name Description Schema

end_date
optional

The ISO 8601 representation of starting point of the date range.

string

start_date
required

The ISO 8601 representation of starting point of the date range.

string

DeliveryLocation

Information about the delivery location

Name Description Schema

address
required

The address information

external_customer_id
optional

The external customer ID assigned to this delivery location (if metadata is available)

string

external_location_id
optional

The external location ID assigned to this delivery location (if metadata is available)

string

name
optional

A name to identify the delivery location

string

Discount

Discount applied to a price

Name Description Schema

from
required

The amount before the discount has been applied

integer (int64)

to
required

The amount after the discount has been applied

integer (int64)

type
required

The type of discount applied

enum (PRICE_LIST_DISCOUNT, MANUAL_ORDER_DISCOUNT)

InvoiceLocation

Information about the invoice location

Name Description Schema

address
required

The address information

email
optional

The email address

string

external_customer_id
optional

The external customer ID assigned to this invoice location (if metadata is available)

string

external_location_id
optional

The external location ID assigned to this invoice location (if metadata is available)

string

name
optional

A name to identify the location

string

Order

Contains all information for a single order

Name Description Schema

messages
required

List of messages sent with the order

< AttachedMessage > array

order_date
required

The ISO 8601 representation of starting point of the date range.

string

order_lines
required

List of order lines

< OrderLine > array

order_number
required

Unique identifier

string

retailer
required

The retailer that has submitted the order

status
required

The order line status

string

OrderLine

Contains all information for a single order line

Name Description Schema

barcode
required

The barcode

string

delivery_location
required

The delivery location for an order line

delivery_window
required

The delivery window for an order line

display_name
required

The name as defined by the brand

string

line_id
required

The order line number

string

metadata
required

A short version of the metadata of this order line

price
required

The price

product_id
optional

The product identifier, as known by the brand

string

quantity
required

The ordered quantity

integer (int32)

remarks
optional

Additional remarks for an order line

string

shop_location
required

The shop location for an order line

size
optional

The size of the variant

string

status
required

The order line status

string

type
required

The order line type, either "PREPACK" or "VARIANT"

enum (PRODUCT, PREPACK)

OrderLineCompactMetadataResponse

Contains a subset of the metadata of this order line

Name Description Schema

external_order_ids
required

The list of order ID’s where this order line is stored in the brand’s system

< string > array

latest_event_log
optional

The latest event log for this order line if any

OrderLineMetadataEventRequest

Name Description Schema

message
required

The message of the event related to the order line

string

OrderLineMetadataEventResponse

Name Description Schema

message
required

The message of the event related to the order line

string

timestamp
required

The time when the event was logged

string

type
required

The type of event, either 'SUCCESS' or 'ERROR'

enum (ERROR, SUCCESS)

OrderLineMetadataRequest

Metadata that is attached to an order line.

Name Description Schema

external_order_ids
optional

The list of order ID’s where this order line is stored in the brand’s system. Required if refs is not provided.

< string > array

refs
optional

[Deprecated] The list of order ID’s where this order line is stored in the brand’s system. Required if external_order_ids is not provided. (Deprecated in favor of external_order_ids)

< string > array

OrderLineMetadataResponse

Name Description Schema

created
required

The date this metadata was created

string

event_log
required

The list with the last events for this order line

external_order_ids
required

The list of order ID’s where this order line is stored in the brand’s system

< string > array

order_number
required

The order number

string

refs
optional

The list of order ID’s where this order line is stored in the brand’s system (Deprecated in favor of external_order_ids)

< string > array

OrderLineRemarks

Name Schema

remarks
required

string

OrderLineStatus

Name Schema

order_line_status
required

enum (SUBMITTED, ACKNOWLEDGED, CONFIRMED, SHIPPED, REJECTED, PARTIALLY_SHIPPED)

OrderLinesResponse

Collection of order lines

Name Schema

items
required

< OrderLine > array

OrderMetaData (Deprecated)

Metadata that is attached to an order. Deprecated in favor of order line metadata

Name Description Schema

created
required
read-only

The date this metadata was created

string

order_number
required
read-only

The order number

string

refs
required

The list of brand specific order information

< string > array

OrderMetaDataRequest (Deprecated)

Metadata that is attached to an order. Deprecated in favor of order line metadata

Name Description Schema

refs
required

The list of brand specific order information

< string > array

OrderOverviewResponse

Name Description Schema

order_date
required

The date the order was created

string

order_number
required

The order number

string

retailer_name
optional

The name of the retailer

string

status
required

enum (SUBMITTED, ACKNOWLEDGED, CONFIRMED, SHIPPED, REJECTED, MIXED, PARTIALLY_SHIPPED)

OrderOverviewResponseArrayWrapper

Name Schema

items
required

next
optional

string

total
required

integer (int32)

PlannedDeliveryWindow

Name Schema

planned_delivery_window
required

Price

Price with currency information

Name Description Schema

currency
required

The currency (default EUR)

string

discounts
required

Discounts that have been applied to the price

< Discount > array

value
required

The value

integer (int64)

Retailer

Information about a retailer

Name Description Schema

id
optional

DEPRECATED: Use external_customer_id and external_location_id in order lines because there may be multiple IDs in an Order.

string

invoice_location
optional

name
required

string

vat_number
optional

string

ShopLocation

Information about the shop location

Name Description Schema

address
optional

The address information

external_customer_id
optional

The external customer ID assigned to this delivery location (if metadata is available)

string

external_location_id
optional

The external location ID assigned to this delivery location (if metadata is available)

string

name
optional

A name to identify the shop location

string

Resources

Brand-order-rules

Get brand-specific order locations rules if any

GET /brand-order-rules/{brandId}/locations
Parameters
Type Name Schema

Path

brandId
required

string (uuid)

Responses
HTTP Code Description Schema

200

Retrieved the brand order locations rules.

401

Request lacks valid authentication.

string

403

Request is not authorized for the authenticated user.

string

Consumes
  • application/json

Produces
  • application/json

Update brand-specific order locations rules

PUT /brand-order-rules/{brandId}/locations
Parameters
Type Name Schema

Path

brandId
required

string (uuid)

Body

body
optional

Responses
HTTP Code Description Schema

200

Updated brand-specific order locations rules

No Content

401

Request lacks valid authentication.

string

403

Request is not authorized for the authenticated user.

string

Consumes
  • application/json

Produces
  • application/json

Order Line Metadata

Create the order line metadata (Deprecated)

POST /orders/{orderNumber}/lines/{lineId}/metadata
Caution

operation.deprecated

Description

Used to store information about the integration with the brand’s system regarding this order line. Deprecated in favor of the idempotent PUT endpoint.

Parameters
Type Name Schema

Path

lineId
required

string

Path

orderNumber
required

string

Body

body
optional

Responses
HTTP Code Description Schema

201

Metadata created.

401

Request lacks valid authentication.

string

404

orderNumber or lineId not found

No Content

Consumes
  • application/json

Produces
  • application/json

Get the order line metadata

GET /orders/{orderNumber}/lines/{lineId}/metadata
Description

Used to store information about the integration with the brand’s system regarding this order line.

Parameters
Type Name Schema

Path

lineId
required

string

Path

orderNumber
required

string

Responses
HTTP Code Description Schema

200

Retrieved the metadata.

401

Request lacks valid authentication.

string

404

No metadata found.

No Content

Consumes
  • application/json

Produces
  • application/json

Update the order line metadata

PUT /orders/{orderNumber}/lines/{lineId}/metadata
Description

Used to store information about the integration with the brand’s system regarding this order line.

Parameters
Type Name Schema

Path

lineId
required

string

Path

orderNumber
required

string

Body

body
optional

Responses
HTTP Code Description Schema

200

Metadata updated

401

Request lacks valid authentication.

string

404

Metadata not found

No Content

Consumes
  • application/json

Produces
  • application/json

Delete the order line metadata (Deprecated)

DELETE /orders/{orderNumber}/lines/{lineId}/metadata
Caution

operation.deprecated

Description

Used to store information about the integration with the brand’s system regarding this order line. Deprecated as information should never be deleted.

Parameters
Type Name Schema

Path

lineId
required

string

Path

orderNumber
required

string

Responses
HTTP Code Description Schema

204

Metadata removed.

No Content

401

Request lacks valid authentication.

string

404

Metadata not found

No Content

Consumes
  • application/json

Produces
  • application/json

Log a new error to the event log

POST /orders/{orderNumber}/lines/{lineId}/metadata/event-log/errors
Description

Used to log business related errors.

Parameters
Type Name Schema

Path

lineId
required

string

Path

orderNumber
required

string

Body

body
optional

Responses
HTTP Code Description Schema

default

successful operation

No Content

Consumes
  • application/json

Produces
  • application/json

Order Metadata

Create the order metadata (Deprecated)

POST /orders/{orderNumber}/metadata
Caution

operation.deprecated

Description

Used to register information to brand specific internal systems. Deprecated in favor of order line metadata.

Parameters
Type Name Schema

Path

orderNumber
required

string

Body

body
optional

Responses
HTTP Code Description Schema

201

Metadata created.

401

Request lacks valid authentication.

string

Consumes
  • application/json

Produces
  • application/json

Get the order metadata (Deprecated)

GET /orders/{orderNumber}/metadata
Caution

operation.deprecated

Description

Used to register information to brand specific internal systems. Deprecated in favor of order line metadata.

Parameters
Type Name Schema

Path

orderNumber
required

string

Responses
HTTP Code Description Schema

200

Retrieved the metadata.

401

Request lacks valid authentication.

string

404

No metadata found.

No Content

Consumes
  • application/json

Produces
  • application/json

Update the order metadata (Deprecated)

PUT /orders/{orderNumber}/metadata
Caution

operation.deprecated

Description

Used to register information to brand specific internal systems. Deprecated in favor of order line metadata.

Parameters
Type Name Schema

Path

orderNumber
required

string

Body

body
optional

Responses
HTTP Code Description Schema

200

Metadata updated.

401

Request lacks valid authentication.

string

Consumes
  • application/json

Produces
  • application/json

Delete the order metadata (Deprecated)

DELETE /orders/{orderNumber}/metadata
Caution

operation.deprecated

Description

Used to register information to brand specific internal systems. Deprecated in favor of order line metadata.

Parameters
Type Name Schema

Path

orderNumber
required

string

Responses
HTTP Code Description Schema

204

Metadata removed.

No Content

401

Request lacks valid authentication.

string

404

Metadata not found

No Content

Consumes
  • application/json

Produces
  • application/json

Orders

Get all orders (paginated)

GET /orders
Parameters
Type Name Description Schema Default

Query

created_after
optional

start date in ISO8601 format

string (int64)

Query

created_before
optional

end date in ISO8601 format

string (int64)

Query

cursor
optional

Deprecated in favor of 'next'

string

Query

limit
optional

maximum number of results to return

integer (int32)

1000

Query

next
optional

string

Query

status
optional

string

Responses
HTTP Code Description Schema

200

Retrieved the orders.

401

Request lacks valid authentication.

string

403

Request is not authorized for the authenticated user.

string

Consumes
  • application/json

Produces
  • application/json

Get an order by order number.

GET /orders/{orderNumber}
Parameters
Type Name Description Schema

Path

orderNumber
required

a valid order number

string

Responses
HTTP Code Description Schema

200

Retrieved the order.

401

Request lacks valid authentication.

string

403

Request is not authorized for the authenticated user.

string

404

Order not found.

string

Consumes
  • application/json

Produces
  • application/json

Get all order lines for an order

GET /orders/{orderNumber}/lines
Parameters
Type Name Schema

Path

orderNumber
required

string

Responses
HTTP Code Description Schema

200

Retrieved the order lines.

401

Request lacks valid authentication.

string

403

Request is not authorized for the authenticated user.

string

404

Order not found.

string

Consumes
  • application/json

Produces
  • application/json

Get an order line by order number and order line ID

GET /orders/{orderNumber}/lines/{lineId}
Parameters
Type Name Schema

Path

lineId
required

string

Path

orderNumber
required

string

Responses
HTTP Code Description Schema

200

Retrieved the order line.

401

Request lacks valid authentication.

string

403

Request is not authorized for the authenticated user.

string

404

Order or order line not found.

string

Consumes
  • application/json

Produces
  • application/json

Update the planned delivery window for an order line

PUT /orders/{orderNumber}/lines/{lineId}/planned-delivery-window
Parameters
Type Name Schema

Path

lineId
required

string

Path

orderNumber
required

string

Body

body
optional

Responses
HTTP Code Description Schema

200

Updated the planned delivery window

401

Request lacks valid authentication.

string

403

Request is not authorized for the authenticated user.

string

404

Order not found.

string

Consumes
  • application/json

Produces
  • application/json

Update the remarks for an order line

PUT /orders/{orderNumber}/lines/{lineId}/remarks
Description

The remarks field is NOT intended for integration information, but for communication between the brand and the retailer.

Parameters
Type Name Schema

Path

lineId
required

string

Path

orderNumber
required

string

Body

body
optional

Responses
HTTP Code Description Schema

200

Updated the remarks

401

Request lacks valid authentication.

string

403

Request is not authorized for the authenticated user.

string

404

Order not found.

string

Consumes
  • application/json

Produces
  • application/json

Update the status for an order line

PUT /orders/{orderNumber}/lines/{lineId}/status
Parameters
Type Name Schema

Path

lineId
required

string

Path

orderNumber
required

string

Body

body
optional

Responses
HTTP Code Description Schema

200

Updated the status

401

Request lacks valid authentication.

string

403

Request is not authorized for the authenticated user.

string

404

Order not found.

string

Consumes
  • application/json

Produces
  • application/json

Security

api_key

An API key is provided to you by FashionTrade.com. In order to use it, supply the key as a bearer token using the Authorization header in a request. E.g. 'Authorization: Bearer <YOUR_API_KEY>'.

Type : apiKey
Name : Authorization
In : HEADER