NAV Navbar
http
  • Introduction
  • Core Resources
  • Quick Start
  • Ads
  • Catalogs
  • Catalog Products
  • Customers
  • Orders
  • Teams
  • Models
  • Errors
  • Javascript SDK
  • Introduction

    Overview

    
                    ,:;;;:,,                    
                 ,;;;;;;;;;;;;,                 
               ;;;;;;;;:::;;;;;;:              
             :;;;;;,         .;;;;.            
            ;;;;;,              :;;;           
           ;;;;;                ``;;;,         
          ;;;;;       ,;;;;;;.  ```,;;:        
         ;;;;;      ;;;;;;;;;;;;`````;;;       
        ,;;;;.    .;;;;;;;;;;;;;;:````;;:      
        ;;;;;    ,;;;;;;;;;;;;;;;``,:``;;.     
       ;;;;;.   `;;;;;;;;;;;;;;;:``:::``;;     
       ;;;;;    ;;;;;;;;;;;;;;;;``:::::`:;;    
      ;;;;;;   ,;;;;;;;;,`.:;;;``,::::::`;;:   
      ;;;;;,   ;;;;;;;,      `: `:::::::``;;   
     .;;;;;`   ;;;;;;:          :::::::::`;;;  
     ;;;;;;   .;;;;;;          ,:::::::::,`;;  
     ;;;;;;   :;;;;;;          :::::::::::`;;: 
     ;;;;;;   :;;;;;;         ::::::::,````,;; 
    ,;;;;;;`  :;;;;;;         ::::,`````````;; 
    :;;;;;;.  :;;;;;;         ` ``````..,,,`;;.
    ;;;;;;;;  .;;;;;;         `::::::::::::`;;;
    ;;;;;;;;   ;;;;;;.         ::::::::::::,:;;
    ;;;;;;;;   ;;;;;;;        ::`:::::::::::,;;
    ;;;;;;;;,  :;;;;;;,       ,::``:::::::::,;;
    :;;;;;;;;   ;;;;;;;`       :::,`,:::::::,;;
    `;;;;;;;;`  :;;;;;;;       :::::``:::::,:;;
     ;;;;;;;;;   ;;;;;;;;`     `:::::```:::`;;;
     ;;;;;;;;;,  .;;;;;;;;;`    ::::::.```:`;;;
     ;;;;;;;;;;   :;;;;;;;;;;;; `:::::::````;;:
      ;;;;;;;;;;   :;;;;;;;;;;;``::::::::``,;; 
      ;;;;;;;;;;;   :;;;;;;;;;;:`.::::::::`;;; 
      `;;;;;;;;;;:   `;;;;;;;;;;``:::::::`,;;: 
       ;;;;;;;;;;;:    :;;;;;;;;.`::::::``;;;  
        ;;;;;;;;;;;;     .;;;;;;;``::::``;;;:  
        .;;;;;;;;;;;;`          ```::```;;;;   
         :;;;;;;;;;;;;;         ``````.;;;;    
          :;;;;;;;;;;;;;;`      `````;;;;;     
           ,;;;;;;;;;;;;;;;;:.```,;;;;;;;      
             ;;;;;;;;;;;;;;;;;;;;;;;;;;;       
              ,;;;;;;;;;;;;;;;;;;;;;;;         
                ,;;;;;;;;;;;;;;;;;;;           
                   :;;;;;;;;;;;;;              
    
    

    The Citrus API makes it possible for your business to create catalogs and products, and to place advertisements based on parameters that you set.

    The Citrus API is organized around REST. The API has predictable, resource-oriented URLS, and uses HTTP response codes to indicate API errors. This API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

    Authentication to the Citrus API is handled through the use of API keys. These tokens are used during communication between your backend and the Citrus API and during communication between a client browser and the Citrus API.

    The Citrus API supports uploading products, catalogs, catalog products, customers, and order information. This data is used in the generation of ads. You can use the Citrus API to request ads and to report on user interactions with those ads.

    Architectural Flow Diagram

    alt text

    Core Resources

    Schemes: https

    Host (Australia): au-integration.citrusad.com

    Host (U.S.): us-integration.citrusad.com

    Host (Staging): staging-integration.citrusad.com

    Base path: /v1

    Authorization: Api Key Security

    Type Name In Description
    apiKey Authorization header When accessing the API a valid API key must be passed in all queries in
    the 'Authorization' header. The following syntax must be used in the
    'Authorization' header.

    Basic my_api_key

    Quick Start

    This Quick Start guides you through all the steps involved in creating an account with Citrus and pushing content to the Citrus API.

    This Quick Start explains:

    In the course of following the instructions in this Quick Start Guide, you will learn all of the skills that you'll need to interact with the Citrus API.

    The Quick Start is targeted at users who are unfamiliar with interacting with APIs. If you already know how to create an account with Citrus, create catalogs, and push products to those catalogs, then you can skip the Quick Start Guide.

    Creating an account

    1. Navigate to au.citrusad.com.
    2. Click Create an account?.
    3. Choose what type of company you are from the menu.
    4. Choose what industry you're in from the menu.
    5. Provide the information requested in the Company Details section.
    6. Provide the information requested in the Personal Details section. This is where you set your password.
    7. Check the green check-mark to the left of the sentence that reads I accept the Terms and Conditions.
    8. Click Register. An activation email will be sent to the email address you provided.
    9. Check your email for the activation email. Click the Activate button in that email.

    When you click the Activate button in the activation email, you will be directed to the Citrus login screen. Log in using the email address and password that you designated during the process of creating an account.

    NOTE: It is not possible to create two separate Citrus accounts with the same email address. Each Citrus account requires its own email address.

    Locating your Team ID

    1. Navigate to staging.citrusad.com.
    2. Log in.
    3. Click your name in the upper-right corner.
    4. Click Integration Settings in the drop-down menu that appears.
    5. Your team ID is displayed in the first field on the screen.

    Locating Your API Key

    1. Navigate to staging.citrusad.com.
    2. Click your name in the upper-right corner.
    3. Click Integration Settings in the drop-down menu that appears.
    4. Click Api Key.
    5. Click the green Show button.
    6. Click the green Copy button. This copies the API key to your clipboard.

    When the API key has been successfully copied to your clipboard, the "Copy" button changes to read "Copied!"

    Note: Your Team ID is necessary for Citrus to identify you. You will use your Team ID to authenticate when you interact with endpoints.

    Creating a Catalog

    Use the curl command in the right pane to create a catalog. Replace the string "your_team_id_goes_here" with your teamId. Replace the string "your_api_key_goes_here" with your API key.

    curl -iX POST "https://staging-integration.citrusad.com/v1/catalogs?teamId=your_team_id_goes_here" \ 
    -H "accept: application/json" \
    -H "content-type: application/json" \
    -H "Authorization: Basic your_api_key_goes_here" \
    -d \
    '{
        "catalogs": [
            {
                "teamId": "44d25f70-b520-40de-8329-0781a9ebcdc8",
                "name": "Second Test Catalog"
            }
        ]
    }'
    

    Correct output looks like this:

    HTTP/2 200
    
    {
        "catalogs": [
            {
                "id":"628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
                "teamId":"44d25f70-b520-40de-8329-0781a9ebcdc8",
                "name":"Second Test Catalog"
            }
        ]
    }
    

    Catalogs and Products

    To send catalog information, first create a catalog. Creating a catalog requires only the team id that was generated when you registered for your Citrus account, and a catalog name.

    After you create a catalog, you can push products to the catalog. The following information is necessary to create a product:

    "Filters" is an array of string identifiers that the e-commerce provider associates with the product, so that they can narrow the scope of products that ads are generated from when they request ads.

    Information about products can be sent to Citrus as described here. What is included in the request is product GTIN, name, size, and list of images (publicly accessible URL to a full-size image).

    You can send up to 100 items (catalogs/catalogProducts/products) per request as a batch while the number of requests is not limited.

    Customers and Orders

    To send customer data to Citrus, follow the instructions in the Customers and Orders section. Citrus needs customer data, transaction data, and order data so that it can generate more relevant ads and so that it can disburse money correctly to the different entities involved in the transaction.

    Sending orders to Citrus is described in the Create or Update Orders section. Apart from regular order and order item fields like customer id, order date, GTIN, quantity, and others, there are a few fields that need a bit more description:

    You can send up to 100 items (customers/orders) per request as a batch while the number of requests is not limited.

    Requesting Ads

    In order to request ads, you must provide a context. This context is used to determine which ads will be served. Below is a description of each context field:

    [["a", "b"], ["c", "d"]]
    
    (a && b) || (c && d)
    

    Details of the ad-generation request are available in the requesting an ad section.

    Requesting Ads and Relevant Products

    We allow our clients to enhance the sorting of their product categories and optimise their search engine results by leveraging our unique targeting algorithm. This feature allows retailers to request a list of relevant products (from their catalog) to load along with requested ads.

    In order to do this, you must provide the following extra property in the context:

    Note that certain rules and restrictions apply to this feature on a per-client basis.

    Ads

    Ads are generated when an e-commerce application makes a request for an ad. This request is received by Citrus's API. The request for an ad contains a context, which represents where that ad will be shown. The context is the browsing behavior of the customer at the time of the impression. A context can be seen in the Models section.

    Based on the information in the context, Citrus locates all the products that match the catalog specified in the context and searches for a campaign that matches the product.

    Requesting an Ad

    POST /v1/ads/generate HTTP/1.1
    Content-Type: application/json
    
    {
        "catalogId": "string",
        "customerId": "string",
        "searchTerm": "string",
        "productFilters": [
            [
                "string"
            ]
        ],
        "categoryHierarchy": [
            "string"
        ],
        "substitutedProductGtin": "string",
        "pageType": "string",
        "currentCartItems": [
            {
                "gtin": "string",
                "quantity": "number",
                "regularUnitPrice": "number",
                "totalOrderItemPriceAfterDiscounts": "number",
                "adId": "string",
                "citrusDiscountAmount": "number",
                "substitutedFor": "object"
            }
        ],
        "maxNumberOfAds": "integer",
        "bannerSlotIds": ["slotId1", "slotId2"],
        "maxNumberOfProducts": "integer",
        "test": "boolean"
    }
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "ads": [
            {
                "id": "string",
                "gtin": "string",
                "discount": {
                    "amount": "number",
                    "minPrice": "number",
                    "maxPerCustomer": "integer"
                },
                "expiry": "string"
            }
        ],
        "banners": [
            {
                "id": "string",
                "slotId": "string",
                "imageUrl": "string",
                "linkUrl": "string",
                "altText": "string",
                "expiry": "string"
            }
        ],
        "products": [
            {
                "id": "string",
                "gtin": "string"
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This generates and returns ads.

    Provide a context object in order to receive relevant ads. The context object includes information about where the ad is going to be shown and to whom it will be shown.

    Parameters

    Name In Type Description
    context *  body Context

    Responses

    Http code Type Description
    200 GenerateAdsResponse On success, returns a list of product ads.
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Report an Ad click

    GET /v1/resource/second-c/{adId} HTTP/1.1
    
    HTTP/1.1 200 OK
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This reports a click for an Ad.

    A Click should be reported whenever a user clicks on an Ad.

    Similar to impressions, the Ad ID must be included in the path of the request.

    Parameters

    Name In Type Description
    adId *  path string
    bfp query string Optional.
    lsid query string Optional.

    Responses

    Http code Type Description
    200 no content OK
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Report an Ad impression

    GET /v1/resource/first-i/{adId} HTTP/1.1
    
    HTTP/1.1 200 OK
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Reports an impression for an Ad.

    An impression should be reported whenever a user views an Ad.

    When reporting an impression, the Ad ID that was provided when generating the ad must be included in the path of the request.

    Parameters

    Name In Type Description
    adId *  path string
    bfp query string Optional.
    lsid query string Optional.

    Responses

    Http code Type Description
    200 no content OK
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Catalogs

    A catalog represents a set of products that is available for sale to customers. Catalogs are defined by retailers.

    Catalogs are lists of products that are currently available. Each team maintains a set of product catalogs. These catalogs are the set of products used to generate ads for particular ad requests.

    Daily updates should be sent to Citrus about product catalogs, so that ads are generated for only those products that are available for purchase. Catalog ids are provided by the client. If a request is received with a catalog id that doesn't exist, it will be created. Otherwise, products inside the existing catalog will be updated. Remember that when requesting an ad, the catalog id is part of the request.

    Create or Update Catalogs

    POST /v1/catalogs HTTP/1.1
    Content-Type: application/json
    
    {
        "catalogs": [
            {
                "id": "string",
                "teamId": "string",
                "name": "string"
            }
        ]
    }
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "catalogs": [
            {
                "id": "string",
                "teamId": "string",
                "name": "string"
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Creates or Updates the list of provided catalogs.

    Parameters

    Name In Type Description
    pushCatalogsRequest *  body PushCatalogsRequest

    Responses

    Http code Type Description
    200 PushCatalogsResponse Returns a list of Catalogs with generated IDs in the same order they were submitted
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Retrieve a list of Catalogs

    GET /v1/catalogs HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "catalogs": [
            {
                "id": "string",
                "teamId": "string",
                "name": "string"
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This returns a list of catalogs. The catalogs are returned sorted by creation date, with the most recent catalogs appearing first. If teamId is set as a parameter, catalogs for that teamId will be returned. Otherwise, catalogs with provided catalogIds will be returned. If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication.

    Parameters

    Name In Type Description
    teamId query string Optional. If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication
    limit query integer Optional.
    skip query integer Optional.
    catalogIds query array[string] Optional.

    Responses

    Http code Type Description
    200 GetCatalogsResponse Returns a list of Catalogs
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Get a Catalog

    GET /v1/catalogs/{catalogId} HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "id": "string",
        "teamId": "string",
        "name": "string"
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This retrieves the catalog. Provide the ID returned by the previous request when creating the catalog.

    Parameters

    Name In Type Description
    catalogId *  path string

    Responses

    Http code Type Description
    200 Catalog Returns a Catalog
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Delete a Catalog

    DELETE /v1/catalogs/{catalogId} HTTP/1.1
    
    HTTP/1.1 200 OK
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This deletes the catalog. Provide the ID returned by the previous request when creating the catalog.

    Parameters

    Name In Type Description
    catalogId *  path string

    Responses

    Http code Type Description
    200 no content OK
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Catalog Products

    A catalog product is a product that is defined in relation to the catalog to which it belongs. Information pertinent to the catalog to which the catalog product belongs is included in the catalog product. This information includes ephemeral information and approximate inventory.

    A CatalogProduct is a decorated Product with information pertinent to the Catalog it belongs to. Information includes ephemeral information like approximate inventory.

    Create or Update CatalogProducts

    POST /v1/catalog-products HTTP/1.1
    Content-Type: application/json
    
    {
        "catalogProducts": [
            {
                "teamId": "string",
                "catalogId": "string",
                "gtin": "string",
                "inventory": "number",
                "price": "number",
                "categoryHierarchy": [
                    "string"
                ],
                "tags": [
                    "string"
                ],
                "filters": [
                    "string"
                ],
                "profit": "number"
            }
        ]
    }
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "catalogProducts": [
            {
                "teamId": "string",
                "catalogId": "string",
                "gtin": "string",
                "inventory": "number",
                "price": "number",
                "categoryHierarchy": [
                    "string"
                ],
                "tags": [
                    "string"
                ],
                "filters": [
                    "string"
                ],
                "profit": "number"
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This creates or updates the list of provided catalog products.

    Parameters

    Name In Type Description
    pushCatalogProductsRequest *  body PushCatalogProductsRequest

    Responses

    Http code Type Description
    200 PushCatalogProductsResponse Returns a list of CatalogProducts with generated IDs in the same order they were submitted
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Retrieve a list of catalogProducts

    GET /v1/catalog-products HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "catalogProducts": [
            {
                "teamId": "string",
                "catalogId": "string",
                "gtin": "string",
                "inventory": "number",
                "price": "number",
                "categoryHierarchy": [
                    "string"
                ],
                "tags": [
                    "string"
                ],
                "filters": [
                    "string"
                ],
                "profit": "number"
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This returns a list of catalog products. The catalog products are returned, sorted by creation date, with the most recent catalog products first. The catalog products that have catalogId and GTINs are returned. If no GTINs are set, then all catalog products belonging to the specified catalog are returned.

    Parameters

    Name In Type Description
    limit query integer Optional.
    skip query integer Optional.
    catalogId *  query string
    gtins query array[string] Optional.

    Responses

    Http code Type Description
    200 GetCatalogProductsResponse Returns a list of CatalogProducts
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Get a CatalogProduct

    GET /v1/catalog-products/{catalogId}/{gtin} HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "teamId": "string",
        "catalogId": "string",
        "gtin": "string",
        "inventory": "number",
        "price": "number",
        "categoryHierarchy": [
            "string"
        ],
        "tags": [
            "string"
        ],
        "filters": [
            "string"
        ],
        "profit": "number"
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This retrieves the catalog product. Provide the id that was returned by the request that you made when you created the catalog product.

    Parameters

    Name In Type Description
    catalogId *  path string
    gtin *  path string

    Responses

    Http code Type Description
    200 CatalogProduct Returns a CatalogProduct
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Delete a CatalogProduct

    DELETE /v1/catalog-products/{catalogId}/{gtin} HTTP/1.1
    
    HTTP/1.1 200 OK
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This deletes the catalog product. Provide the id returned by the request that you made when you created the catalog product.

    Parameters

    Name In Type Description
    catalogId *  path string
    gtin *  path string

    Responses

    Http code Type Description
    200 no content OK
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Customers

    A customer is a visitor to a retailer's e-commerce platform.

    Create or Update Customers

    POST /v1/customers HTTP/1.1
    Content-Type: application/json
    
    {
        "customers": [
            {
                "id": "string",
                "teamId": "string",
                "yearOfBirth": "integer",
                "gender": "string",
                "suburb": "string",
                "postcode": "string"
            }
        ]
    }
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "customers": [
            {
                "id": "string",
                "teamId": "string",
                "yearOfBirth": "integer",
                "gender": "string",
                "suburb": "string",
                "postcode": "string"
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    This creates or updates the list of provided customers.

    Parameters

    Name In Type Description
    pushCustomersRequest *  body PushCustomersRequest

    Responses

    Http code Type Description
    200 PushCustomersResponse Returns a list of Customers with generated IDs in the same order they were submitted.
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Retrieve a list of Customers

    GET /v1/customers HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "customers": [
            {
                "id": "string",
                "teamId": "string",
                "yearOfBirth": "integer",
                "gender": "string",
                "suburb": "string",
                "postcode": "string"
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Returns a list of customers. The customers are returned sorted by creation date with the most recent customers appearing first. If teamId is set as a parameter, customers for that teamId will be returned, otherwise, customers with provided customerIds will be returned. If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication.

    Parameters

    Name In Type Description
    teamId query string Optional. If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication.
    limit query integer Optional.
    skip query integer Optional.
    customerIds query array[string] Optional.

    Responses

    Http code Type Description
    200 GetCustomersResponse Returns a list of Customers
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Retrieve a Customer

    GET /v1/customers/{customerId} HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "id": "string",
        "teamId": "string",
        "yearOfBirth": "integer",
        "gender": "string",
        "suburb": "string",
        "postcode": "string"
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Retrieves the customer. Provide the ID returned by the previous request when creating the customer.

    Parameters

    Name In Type Description
    customerId *  path string

    Responses

    Http code Type Description
    200 Customer Returns a Customer
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Delete a Customer

    DELETE /v1/customers/{customerId} HTTP/1.1
    
    HTTP/1.1 200 OK
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Deletes the customer. Provide the ID returned by the previous request when creating the customer.

    Parameters

    Name In Type Description
    customerId *  path string

    Responses

    Http code Type Description
    200 no content OK
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Orders

    An order is an agreement between a customer and a retailer that says that the customer agrees to buy a product from the retailer.

    Create or Update Orders

    POST /v1/orders HTTP/1.1
    Content-Type: application/json
    
    {
        "orders": [
            {
                "id": "string",
                "teamId": "string",
                "customerId": "string",
                "orderDate": "string",
                "orderItems": [
                    {
                        "gtin": "string",
                        "quantity": "number",
                        "regularUnitPrice": "number",
                        "totalOrderItemPriceAfterDiscounts": "number",
                        "adId": "string",
                        "citrusDiscountAmount": "number",
                        "substitutedFor": {}
                    }
                ]
            }
        ]
    }
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "orders": [
            {
                "id": "string",
                "teamId": "string",
                "customerId": "string",
                "orderDate": "string",
                "orderItems": [
                    {
                        "gtin": "string",
                        "quantity": "number",
                        "regularUnitPrice": "number",
                        "totalOrderItemPriceAfterDiscounts": "number",
                        "adId": "string",
                        "citrusDiscountAmount": "number",
                        "substitutedFor": "object"
                    }
                ]
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Creates or Updates the list of provided orders.

    Parameters

    Name In Type Description
    pushOrdersRequest *  body PushOrdersRequest

    Responses

    Http code Type Description
    200 PushOrdersResponse Returns a list of Orders with generated IDs in the same order they were submitted
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Retrieve a list of Orders

    GET /v1/orders HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "orders": [
            {
                "id": "string",
                "teamId": "string",
                "customerId": "string",
                "orderDate": "string",
                "orderItems": [
                    {
                        "gtin": "string",
                        "quantity": "number",
                        "regularUnitPrice": "number",
                        "totalOrderItemPriceAfterDiscounts": "number",
                        "adId": "string",
                        "citrusDiscountAmount": "number",
                        "substitutedFor": "object"
                    }
                ]
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Returns a list of orders. The orders are returned sorted by creation date with the most recent orders appearing first. If teamId is set as a parameter, orders for that teamId will be returned, otherwise, orders with provided orderIds will be returned. If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication.

    Parameters

    Name In Type Description
    teamId query string Optional. If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication.
    limit query integer Optional.
    skip query integer Optional.
    orderIds query array[string] Optional.

    Responses

    Http code Type Description
    200 GetOrdersResponse Returns a list of Orders
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Retrieve an Order

    GET /v1/orders/{orderId} HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "id": "string",
        "teamId": "string",
        "customerId": "string",
        "orderDate": "string",
        "orderItems": [
            {
                "gtin": "string",
                "quantity": "number",
                "regularUnitPrice": "number",
                "totalOrderItemPriceAfterDiscounts": "number",
                "adId": "string",
                "citrusDiscountAmount": "number",
                "substitutedFor": "object"
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Retrieves an order. Provide the ID returned by the previous request when creating the orders.

    Parameters

    Name In Type Description
    orderId *  path string

    Responses

    Http code Type Description
    200 Order Returns an Order
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Delete an Order

    DELETE /v1/orders/{orderId} HTTP/1.1
    
    HTTP/1.1 200 OK
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Deletes the orders. Provide the ID returned by the previous request when creating the orders.

    Parameters

    Name In Type Description
    orderId *  path string

    Responses

    Http code Type Description
    200 no content OK
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Teams

    A team represents an account in the Citrus API. You can think of a team as an "account ID". A team can have multiple catalogs (for instance, a regular catalog and a premium catalog, or catalogs for different geographical regions).

    Retrieve list of all connected teams

    GET /v1/teams HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "teams": [
            {
                "citrusTeamId": "string",
                "thirdPartyTeamId": "string",
                "permissions": [
                    {
                        "domain": "string",
                        "accesses": [
                            "string"
                        ]
                    }
                ]
            }
        ]
    }
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Returns a list of all connected teams that this team can do operations on behalf of.

    Responses

    Http code Type Description
    200 GetTeamsResponse Returns a list of connected teams info
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Test if authentication works or not

    GET /v1/authenticate HTTP/1.1
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    "string"
    
    HTTP/1.1 400 Bad Request
    
    HTTP/1.1 401 Unauthorized
    
    HTTP/1.1 403 Forbidden
    
    HTTP/1.1 404 Not Found
    
    HTTP/1.1 429 Too Many Requests
    
    HTTP/1.1 500 Internal Server Error
    
    HTTP/1.1 502 Bad Gateway
    
    HTTP/1.1 503 Service Unavailable
    
    HTTP/1.1 504 Gateway Timeout
    
    HTTP/1.1 [default]
    

    Returns a message indicating the team you are acting as

    Responses

    Http code Type Description
    200 string A successful message indicating which team you are acting as
    400 no content
    401 no content
    403 no content
    404 no content
    429 no content
    500 no content
    502 no content
    503 no content
    504 no content
    default no content

    Models

    ErrorResponse

    {
        "message": "string",
        "additionalInfo": [
            {
                "message": "string",
                "code": "string"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    message *  string
    additionalInfo array[object]

    Context

    {
        "catalogId": "string",
        "customerId": "string",
        "searchTerm": "string",
        "productFilters": [
            [
                "string"
            ]
        ],
        "categoryHierarchy": [
            "string"
        ],
        "substitutedProductGtin": "string",
        "pageType": "string",
        "currentCartItems": [
            {
                "gtin": "string",
                "quantity": "number",
                "regularUnitPrice": "number",
                "totalOrderItemPriceAfterDiscounts": "number",
                "adId": "string",
                "citrusDiscountAmount": "number",
                "substitutedFor": "object"
            }
        ],
        "maxNumberOfAds": "integer",
        "maxNumberOfProducts": "integer",
        "test": "boolean"
    }
    

    Fields

    Name Type Format Description
    catalogId *  string
    customerId string
    searchTerm string
    productFilters array[array[string]]
    categoryHierarchy array[string]
    substitutedProductGtin string
    pageType string
    Acceptable values:
    • Home
    • Category
    • Search
    • Specials
    • PastOrder
    • Substitution
    • Samples
    currentCartItems array[OrderItem]
    maxNumberOfAds integer
    maxNumberOfProducts integer
    test boolean

    GenerateAdsResponse

    {
        "ads": [
            {
                "id": "string",
                "gtin": "string",
                "discount": {
                    "amount": "number",
                    "minPrice": "number",
                    "maxPerCustomer": "integer"
                },
                "expiry": "string"
            }
        ],
        "products": [
            {
                "id": "string",
                "gtin": "string"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    ads array[ProductAd]
    products array[object]

    ProductAd

    {
        "id": "string",
        "gtin": "string",
        "discount": {
            "amount": "number",
            "minPrice": "number",
            "maxPerCustomer": "integer"
        },
        "expiry": "string"
    }
    

    Fields

    Name Type Format Description
    id *  string
    gtin *  string
    discount Discount
    expiry string date-time

    Purchase

    {
        "orderId": "string",
        "productAdIds": [
            "string"
        ]
    }
    

    Fields

    Name Type Format Description
    orderId *  string
    productAdIds *  array[string]

    Discount

    {
        "amount": "number",
        "minPrice": "number",
        "maxPerCustomer": "integer"
    }
    

    Fields

    Name Type Format Description
    amount number
    minPrice number
    maxPerCustomer integer

    Catalog

    {
        "id": "string",
        "teamId": "string",
        "name": "string"
    }
    

    Fields

    Name Type Format Description
    id string
    teamId string If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication
    name *  string

    GetCatalogsResponse

    {
        "catalogs": [
            {
                "id": "string",
                "teamId": "string",
                "name": "string"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    catalogs *  array[Catalog]

    PushCatalogsRequest

    {
        "catalogs": [
            {
                "id": "string",
                "teamId": "string",
                "name": "string"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    catalogs *  array[Catalog]

    PushCatalogsResponse

    {
        "catalogs": [
            {
                "id": "string",
                "teamId": "string",
                "name": "string"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    catalogs *  array[Catalog]

    UpdateCatalogRequest

    {
        "catalog": {
            "id": "string",
            "teamId": "string",
            "name": "string"
        }
    }
    

    Fields

    Name Type Format Description
    catalog *  Catalog

    CatalogProduct

    {
        "teamId": "string",
        "catalogId": "string",
        "gtin": "string",
        "inventory": "number",
        "price": "number",
        "categoryHierarchy": [
            "string"
        ],
        "tags": [
            "string"
        ],
        "filters": [
            "string"
        ],
        "profit": "number"
    }
    

    Fields

    Name Type Format Description
    teamId string If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication
    catalogId *  string
    gtin *  string
    inventory number
    price number
    categoryHierarchy array[string]
    tags array[string]
    filters array[string]
    profit number

    GetCatalogProductsResponse

    {
        "catalogProducts": [
            {
                "teamId": "string",
                "catalogId": "string",
                "gtin": "string",
                "inventory": "number",
                "price": "number",
                "categoryHierarchy": [
                    "string"
                ],
                "tags": [
                    "string"
                ],
                "filters": [
                    "string"
                ],
                "profit": "number"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    catalogProducts *  array[CatalogProduct]

    PushCatalogProductsRequest

    {
        "catalogProducts": [
            {
                "teamId": "string",
                "catalogId": "string",
                "gtin": "string",
                "inventory": "number",
                "price": "number",
                "categoryHierarchy": [
                    "string"
                ],
                "tags": [
                    "string"
                ],
                "filters": [
                    "string"
                ],
                "profit": "number"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    catalogProducts *  array[CatalogProduct]

    PushCatalogProductsResponse

    {
        "catalogProducts": [
            {
                "teamId": "string",
                "catalogId": "string",
                "gtin": "string",
                "inventory": "number",
                "price": "number",
                "categoryHierarchy": [
                    "string"
                ],
                "tags": [
                    "string"
                ],
                "filters": [
                    "string"
                ],
                "profit": "number"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    catalogProducts *  array[CatalogProduct]

    UpdateCatalogProductRequest

    {
        "catalog": {
            "teamId": "string",
            "catalogId": "string",
            "gtin": "string",
            "inventory": "number",
            "price": "number",
            "categoryHierarchy": [
                "string"
            ],
            "tags": [
                "string"
            ],
            "filters": [
                "string"
            ],
            "profit": "number"
        }
    }
    

    Fields

    Name Type Format Description
    catalog CatalogProduct

    Customer

    {
        "id": "string",
        "teamId": "string",
        "yearOfBirth": "integer",
        "gender": "string",
        "suburb": "string",
        "postcode": "string"
    }
    

    Fields

    Name Type Format Description
    id string
    teamId string If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication
    yearOfBirth integer
    gender string
    Acceptable values:
    • Male
    • Female
    • Other
    suburb string
    postcode string

    GetCustomersResponse

    {
        "customers": [
            {
                "id": "string",
                "teamId": "string",
                "yearOfBirth": "integer",
                "gender": "string",
                "suburb": "string",
                "postcode": "string"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    customers *  array[Customer]

    PushCustomersRequest

    {
        "customers": [
            {
                "id": "string",
                "teamId": "string",
                "yearOfBirth": "integer",
                "gender": "string",
                "suburb": "string",
                "postcode": "string"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    customers *  array[Customer]

    PushCustomersResponse

    {
        "customers": [
            {
                "id": "string",
                "teamId": "string",
                "yearOfBirth": "integer",
                "gender": "string",
                "suburb": "string",
                "postcode": "string"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    customers *  array[Customer]

    UpdateCustomerRequest

    {
        "customer": {
            "id": "string",
            "teamId": "string",
            "yearOfBirth": "integer",
            "gender": "string",
            "suburb": "string",
            "postcode": "string"
        }
    }
    

    Fields

    Name Type Format Description
    customer *  Customer

    GetOrdersResponse

    {
        "orders": [
            {
                "id": "string",
                "teamId": "string",
                "customerId": "string",
                "orderDate": "string",
                "orderItems": [
                    {
                        "gtin": "string",
                        "quantity": "number",
                        "regularUnitPrice": "number",
                        "totalOrderItemPriceAfterDiscounts": "number",
                        "adId": "string",
                        "citrusDiscountAmount": "number",
                        "substitutedFor": "object"
                    }
                ]
            }
        ]
    }
    

    Fields

    Name Type Format Description
    orders *  array[Order]

    Order

    {
        "id": "string",
        "teamId": "string",
        "customerId": "string",
        "orderDate": "string",
        "orderItems": [
            {
                "gtin": "string",
                "quantity": "number",
                "regularUnitPrice": "number",
                "totalOrderItemPriceAfterDiscounts": "number",
                "adId": "string",
                "citrusDiscountAmount": "number",
                "substitutedFor": "object"
            }
        ]
    }
    

    Fields

    Name Type Format Description
    id string
    teamId string If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication
    customerId string
    orderDate *  string date-time
    orderItems *  array[OrderItem]

    OrderItem

    {
        "gtin": "string",
        "quantity": "number",
        "regularUnitPrice": "number",
        "totalOrderItemPriceAfterDiscounts": "number",
        "adId": "string",
        "citrusDiscountAmount": "number",
        "substitutedFor": "object"
    }
    

    Fields

    Name Type Format Description
    gtin *  string
    quantity *  number
    regularUnitPrice *  number
    totalOrderItemPriceAfterDiscounts *  number
    adId string
    citrusDiscountAmount number
    substitutedFor object

    PushOrdersRequest

    {
        "orders": [
            {
                "id": "string",
                "teamId": "string",
                "customerId": "string",
                "orderDate": "string",
                "orderItems": [
                    {
                        "gtin": "string",
                        "quantity": "number",
                        "regularUnitPrice": "number",
                        "totalOrderItemPriceAfterDiscounts": "number",
                        "adId": "string",
                        "citrusDiscountAmount": "number",
                        "substitutedFor": "object"
                    }
                ]
            }
        ]
    }
    

    Fields

    Name Type Format Description
    orders *  array[Order]

    PushOrdersResponse

    {
        "orders": [
            {
                "id": "string",
                "teamId": "string",
                "customerId": "string",
                "orderDate": "string",
                "orderItems": [
                    {
                        "gtin": "string",
                        "quantity": "number",
                        "regularUnitPrice": "number",
                        "totalOrderItemPriceAfterDiscounts": "number",
                        "adId": "string",
                        "citrusDiscountAmount": "number",
                        "substitutedFor": "object"
                    }
                ]
            }
        ]
    }
    

    Fields

    Name Type Format Description
    orders *  array[Order]

    UpdateOrderRequest

    {
        "order": {
            "id": "string",
            "teamId": "string",
            "customerId": "string",
            "orderDate": "string",
            "orderItems": [
                {
                    "gtin": "string",
                    "quantity": "number",
                    "regularUnitPrice": "number",
                    "totalOrderItemPriceAfterDiscounts": "number",
                    "adId": "string",
                    "citrusDiscountAmount": "number",
                    "substitutedFor": "object"
                }
            ]
        }
    }
    

    Fields

    Name Type Format Description
    order *  Order

    GetProductsResponse

    {
        "products": [
            {
                "gtin": "string",
                "name": "string",
                "size": "string",
                "images": [
                    "string"
                ]
            }
        ]
    }
    

    Fields

    Name Type Format Description
    products *  array[Product]

    Product

    {
        "gtin": "string",
        "name": "string",
        "size": "string",
        "images": [
            "string"
        ]
    }
    

    Fields

    Name Type Format Description
    gtin *  string
    name string
    size string
    images array[string]

    PushProductsRequest

    {
        "products": [
            {
                "gtin": "string",
                "name": "string",
                "size": "string",
                "images": [
                    "string"
                ]
            }
        ]
    }
    

    Fields

    Name Type Format Description
    products *  array[Product]

    PushProductsResponse

    {
        "products": [
            {
                "gtin": "string",
                "name": "string",
                "size": "string",
                "images": [
                    "string"
                ]
            }
        ]
    }
    

    Fields

    Name Type Format Description
    products *  array[Product]

    UpdateProductRequest

    {
        "product": {
            "gtin": "string",
            "name": "string",
            "size": "string",
            "images": [
                "string"
            ]
        }
    }
    

    Fields

    Name Type Format Description
    product *  Product

    GetTeamsResponse

    {
        "teams": [
            {
                "citrusTeamId": "string",
                "thirdPartyTeamId": "string",
                "permissions": [
                    {
                        "domain": "string",
                        "accesses": [
                            "string"
                        ]
                    }
                ]
            }
        ]
    }
    

    Fields

    Name Type Format Description
    teams array[object]

    Permission

    {
        "domain": "string",
        "accesses": [
            "string"
        ]
    }
    

    Fields

    Name Type Format Description
    domain *  string
    accesses *  array[string]

    Errors

    The Citrus API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request was malformed or missing fields.
    401 Unauthorized -- Your API key is expired or not valid.
    403 Forbidden -- Your API key does not grant you access to this endpoint.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    Javascript SDK

    Including Citrus.js

    The intended use for the Citrus JavaScript SDK is to register impressions and clicks. The implementation of the Citrus JS SDK is an important part of the overall system that helps us monitor and detect fraudulent behaviour from potential malicious actors (click fraud etc).

    The setup is fairly straight forward and the API currently exposes only two methods.

    Including a script file using a script tag:

    <script type="text/javascript" src="https://assets.citrusad.net/citrusjs/0.1.0/citrus.js"></script>
    

    Usages

    <script type="text/javascript" src="https://assets.citrusad.net/citrusjs/0.1.0/citrus.js"></script>
    <script type="text/javascript">
      var citrusAd = CitrusAd.init(
        'https://staging-integration.citrusad.com/v1',
        /*
          Above address determines which environment clicks and impressions are being reported to.
          - Staging: https://staging-integration.citrusad.com/v1
          - Production AU: https://au-integration.citrusad.com/v1
          - Production US: https://us-integration.citrusad.com/v1
        */
        {
          disableTracking: false // Optional: defaults to true.
        }
      );
      citrusAd.reportClick('adId').then(function (result) {
        console.log(result);
      }).catch(function (error) {
        console.log(error);
      })
      citrusAd.reportImpression('adId').then(function (result) {
        console.log(result);
      }).catch(function (error) {
        console.log(error);
      })
    </script>