Syncing order data via backend (recommended)
To send order data to CitrusAd, use a command similar to the command below. Note that the data in the orders field below is dummy data, and is provided here only as an example. These examples all display the standard integration.
Integrating a marketplace sellerId?
Be sure to read the Marketplace sellerId section below.
Single item orders
Below is the context for a customer who has purchased a single item:
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
}
]
}
If successful, the following object will be returned:
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
}
],
"orderDate": "2021-12-02T15:00:00Z",
}
]
}
OrderDate format
OrderDate in the format above is read as UTC time. You will need to synchronise in UTC.
Alternatively, you can set an offset for your timezone, subsituting
Zfor+HH:MMrelevant to your timezone. For example: “orderDate”:“2021-12-02T15:00:00+10:00"will specify the timezone is UTC+10.
Multi-item orders
Below is the context for a customer who has purchased multiple items - there are multiple items in the orderItems array:
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
},
{
"gtin": "351998532P",
"quantity": 1,
"regularUnitPrice": "2.50",
"totalOrderItemPriceAfterDiscounts": "2.50"
}
]
}
]
}
If successful, the following object will be returned:
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
},
{
"regularUnitPrice": 2.50,
"citrusDiscountAmount": null,
"gtin": "351998532P",
"adId": "",
"quantity": 1,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 2.50
}
],
"orderDate": "2021-12-02T15:00:00Z",
}
]
}
Syncing multiple orders
If you are syncing multiple orders, you can send up to 100 items as a batch with each request. The number of requests you can make is unlimited. The payload order pushed is the same order as the result returned. This makes it possible for the data to remain congruent with the order representation in your backend.
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
},
{
"customerId": "rw3-v3ag-ol0",
"sessionId": "2m342-2dfe-0f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
"orderItems": [
{
"gtin": "5431998566P",
"quantity": 2,
"regularUnitPrice": "2.00",
"totalOrderItemPriceAfterDiscounts": "4.00"
}
]
}
]
}
If successful, the following object will be returned:
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
}
],
"orderDate": "2021-12-02T15:00:00Z"
},
{
"adIds": null,
"teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
"customerId": "rw3-v3ag-ol0",
"sessionId": "2m342-2dfe-0f",
"id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
"orderItems": [
{
"regularUnitPrice": 2.00,
"citrusDiscountAmount": null,
"gtin": "5431998566P",
"adId": "",
"quantity": 2,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 4.00
}
],
"orderDate": "2021-12-02T15:00:00Z"
}
]
}
Marketplace sellerId
If you are onboarding marketplace sellers you need to synchronise the sellerId where applicable when reporting orders. In the event the purchased product does not have a sellerId, it can be omitted.
If you are not onboarding marketplace sellers, you do not need to specify sellerId in the order report
Below is an example of an order where one product is from a marketplace seller and another is not a marketplace product:
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00",
"sellerId": "10sa-3s33-j8e3"
}
]
},
{
"gtin": "351998532P",
"quantity": 1,
"regularUnitPrice": "2.50",
"totalOrderItemPriceAfterDiscounts": "2.50"
}
]
}
]
}
Syncing order data via frontend (not recommended)
If you are unable to sync order data via the backend, CitrusAd supports an open API as specified below. It is recommended that this is only used when backend integration and file synchronising capabilities are not possible.
Reporting any data via the frontend is a higher risk than a standard backend integration.
Integrators should be aware of the risk that while the reporting domain is not currently blocked by adblockers, it may be in the future, at which point CitrusAd will not be responsible for any lost data.
Open API Specification:
openapi: 3.0.1
info:
title: Citrus
version: 1.0.0
paths:
/v1/resource/third-o:
get:
tags:
- resource
summary: Report an order.
operationId: resource-third-o
parameters:
- in: query
name: key
description: |
(Publishable) API key.
schema:
type: string
required: true
- in: query
name: teaid
description: |
Team id.
schema:
type: string
required: false
- in: query
name: catid
description: |
Catalog id.
schema:
type: string
required: true
- in: query
name: ordid
description: |
Order id.
schema:
type: string
required: true
- in: query
name: ordts
description: |
Order timestamp as a string in RFC3339.
schema:
type: string
required: true
- in: query
name: sesid
description: |
Session id.
schema:
type: string
required: true
- in: query
name: cusid
description: |
Customer id.
schema:
type: string
- in: query
name: procods
description: |
Product codes. Related by index to pris and quas. The length must match pris and quas.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "procods=7913494","procods=6815686" ]
summary: "product code list"
required: true
- in: query
name: pris
description: |
Prices as strings. Related by index to itsids and quas. The length must match pris and quas.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "pris=7913494","pris=6815686" ]
summary: "prices list"
required: true
- in: query
name: quas
description: |
Quantities as strings. Related by index to itsids and pris. The length must match itsids and pris.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "quas=7913494","quas=6815686" ]
summary: "quantity list"
required: true
responses:
200:
description: Successful operation.
content:
application/json:
schema:
type: object
400:
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
401:
description: Invalid credentails.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: Insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
500:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- apiKey: []
components:
schemas:
ErrorResponse:
type: object
properties:
error:
type: object
properties:
message:
type: string
securitySchemes:
apiKey:
type: apiKey
name: Authorization
in: header
If you're unsure about the terms outlined in this section, please visit the reference page.
Retrieving order information
If you wish to verify order information within CitrusAd, you will make a GET request to the /orders/ API with the order id.
GET $BASE_URL/v1/orders/<ORDER_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
You will retrieve all information related to the order stored within the CitrusAd system.
In the event the order is not found, it has likely not been ingested into the CitrusAd system.