Syncing order data via API

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.

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": [
       {
        "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": null,
            "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",
        }
    ]
}

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": [
       {
        "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": null,
            "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": [
        {
              "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"              
                }
              ]
            },
        {
              "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": "",
            "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": "",
            "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"
        }
    ]
}

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.