{ "openapi": "3.1.0", "info": { "title": "Epsilon Retail Media Integration API", "version": "1", "x-source": "https://developers.citrusad.com/integration/reference/" }, "servers": [ { "url": "https://integration-BASE-URL.citrusad.com/v1/" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "name": "Authorization", "in": "header", "x-bearer-format": "basic", "x-default": "YOUR_API_KEY" } } }, "security": [ { "sec0": [] } ], "paths": { "/ads/generate": { "post": { "summary": "Generate product and banner ads", "description": "", "operationId": "generate", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "catalogId", "placement", "maxNumberOfAds" ], "properties": { "catalogId": { "type": "string", "description": "The catalogId you are requesting ads for. Typically a single identifier for a retailer." }, "placement": { "type": "string", "description": "The placement you are requesting ads for." }, "customerId": { "type": "string", "description": "Your unique customerId. Optional." }, "sessionId": { "type": "string", "description": "Unique sessionId used for attribution. Required to be consistent between a user's session and order reporting." }, "searchTerm": { "type": "string", "description": "Used for search placements. The exact search term entered by the customer on your site." }, "targetedProductGtin": { "type": "string", "description": "Used for cross-sell placements. The product code that is being advertised against" }, "maxNumberOfAds": { "type": "integer", "description": "The maximum number of product ads to receive.", "format": "int32" }, "contentStandardId": { "type": "string", "description": "The banner contentStandardId. Required for banners." }, "bannerSlotIds": { "type": "array", "description": "The banner slots ads are required. Will be superseded by bannerSlots array object.", "items": { "type": "string" } }, "productFilters": { "type": "string", "description": "An array or arrays are required depending on your ad generation filtering. Used in category placements or any other placement to further define business rules. Not currently compatible with cross-sell or upsell placements.", "default": "[ [ \"category:Frozen\" ], [\"Location:Brisbane Central\"]]", "format": "json" }, "options": { "type": "array", "items": { "properties": { "filtermode": { "type": "string", "description": "Defines the ad generation filtering mode.", "default": "AndOr" }, "cached": { "type": "boolean", "description": "Defines if the retailer expects to cache the adId", "default": false }, "includeAdvertiserInfo": { "type": "boolean", "description": "Defines if the retailer requires advertiser information to comply with the EU's Digital Services Act", "default": true } }, "type": "object" } }, "bannerSlots": { "type": "array", "description": "The banner slots that are requested. Specifying maxNumberOfAds for the banner allows you to retrieve multiple of the same banner slot.", "items": { "properties": { "slotId": { "type": "string", "description": "The bannerSlotId ads are required for." }, "maxNumberOfAds": { "type": "integer", "description": "The maximum number of product ads to receive.", "format": "int32" } }, "type": "object" } }, "audience": { "type": "array", "items": { "properties": { "segmentIds": { "type": "array", "description": "The list of segment IDs that the customer can access.", "default": [], "items": { "type": "string" } }, "sourceId": { "type": "string", "description": "The agreed ID of the source between Epsilon and yourself. Used when multiple sources are used for segments. Not required if only syncing from one source.", "default": "retailer-cdp-1" } }, "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"ads\": [\n {\n \"id\": \"string\",\n \"gtin\": \"string\",\n \"discount\": {\n \"amount\": \"number\",\n \"minPrice\": \"number\",\n \"maxPerCustomer\": \"integer\"\n },\n \"expiry\": \"string\",\n \"position\": \"integer\",\n \t\"metadata\": {\n \t\t\t\"advertiserInfo\": {\n \t\t\t\t\t\"advertiser\": \"string\",\n \t\t\t\"onBehalfOf\": \"string\",\n \t\t\t},\n {\n \"id\": \"string\",\n \"gtin\": \"string\",\n \"discount\": {\n \"amount\": \"number\",\n \"minPrice\": \"number\",\n \"maxPerCustomer\": \"integer\"\n },\n \"expiry\": \"string\",\n \"position\": \"integer\"\n \t\"metadata\": {\n \t\t\t\"advertiserInfo\": {\n \t\t\t\t\t\"advertiser\": \"string\",\n \t\t\t\"onBehalfOf\": \"string\",\n },\n {\n \"id\": \"string\",\n \"gtin\": \"string\",\n \"discount\": {\n \"amount\": \"number\",\n \"minPrice\": \"number\",\n \"maxPerCustomer\": \"integer\"\n },\n \"expiry\": \"string\",\n \"position\": \"integer\"\n \t\"metadata\": {\n \t\t\t\"advertiserInfo\": {\n \t\t\t\t\t\"advertiser\": \"string\",\n \t\t\t\"onBehalfOf\": \"string\", \n }\n ],\n \"banners\": [\n {\n \"id\": \"string\",\n \"contentStandardId\": \"string\",\n \"slotId\": \"string\",\n \"imageUrl\": \"string\",\n \"linkUrl\": \"string\",\n \"altText\": \"string\",\n \"text\": \"\",\n \"gtins\": [\n \"string\",\n \"string\"\n ],\n \"expiry\": \"2022-03-10T05:53:14.653320236Z\",\n \"tags\": {}\n }\n ],\n \"products\": [], \n \"metadata\": []\n\n}" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "" } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } }, "/ads/bannerx": { "post": { "summary": "Generate banner X ads", "description": "", "operationId": "bannerx", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "catalogId", "placement" ], "properties": { "catalogId": { "type": "string", "description": "The catalogId you are requesting ads for. Typically a single identifier for a retailer." }, "placement": { "type": "string", "description": "The placement you are requesting ads for." }, "customerId": { "type": "string", "description": "Your unique customerId. Optional." }, "sessionId": { "type": "string", "description": "Unique sessionId used for attribution. Required to be consistent between a user's session and order reporting." }, "searchTerm": { "type": "string", "description": "Used for search placements. The exact search term entered by the customer on your site." }, "contentStandardId": { "type": "string", "description": "The banner contentStandardId. Required for banners." }, "bannerSlotIds": { "type": "array", "description": "The banner slots ads are required for.", "items": { "properties": { "slotId": { "type": "string", "description": "The bannerSlotId ads are required for." }, "maxNumberOfAds": { "type": "integer", "description": "The maximum number of product ads to receive.", "format": "int32" } }, "type": "object" } }, "productFilters": { "type": "string", "description": "An array or arrays are required depending on your ad generation filtering. Used in category placements or any other placement to further define business rules. Not currently compatible with cross-sell or upsell placements.", "default": "[ [ \"category:Frozen\" ], [\"Location:Brisbane Central\"]]", "format": "json" }, "options": { "type": "array", "items": { "properties": { "filtermode": { "type": "string", "description": "Defines the ad generation filtering mode.", "default": "AndOr" }, "cached": { "type": "boolean", "description": "Defines if the retailer expects to cache the adId", "default": false }, "includeAdvertiserInfo": { "type": "boolean", "description": "Defines if the retailer requires advertiser information to comply with the EU's Digital Services Act", "default": true } }, "type": "object" } }, "audience": { "type": "array", "items": { "properties": { "segmentIds": { "type": "array", "description": "The list of segment IDs that the customer can access.", "default": [], "items": { "type": "string" } }, "sourceId": { "type": "string", "description": "The agreed ID of the source between Epsilon and yourself. Used when multiple sources are used for segments. Not required if only syncing from one source.", "default": "retailer-cdp-1" } }, "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"ads\": [\n {\n \"contentStandardId\": \"string\",\n \"slotId\": \"string\",\n \"banners\": [\n {\n \"citrusAdId\": \"string\",\n \"citrusCampaignName\": \"string\",\n \"citrusContentStandardId\": \"string\",\n \"citrusSlotId\": \"string\",\n \"citrusExpiry\": \"string\",\n \"headingText\": \"string\",\n \"bannerText\": \"string\",\n \"bannerTextColour\": \"string\",\n \"ctaFlag\": boolean,\n \"ctaText\": \"string\",\n \"ctaTextAccessibility\": \"string\",\n \"ctaLink\": \"string\",\n \"backgroundColour\": \"string\",\n \"backgroundImage\": \"string\",\n \"backgroundImagePosition\": \"string\",\n \"heroImage\": \"string\",\n \"heroImageAltText\": \"string\",\n \"secondaryHeroImage\": \"string\",\n \"secondaryHeroImageAltText\": \"string\",\n \"tags\": {},\n \"gtins\": [\n \"string\",\n \"string\"\n ],\n \"position\": integer,\n \t\"metadata\": {\n \t\t\t\t\t\t\t\"advertiserInfo\": {\n \t\t\t\t\t\t\t\"advertiser\": \"string\",\n \t\t\t\t\t\t\t\"onBehalfOf\": \"string\"\n }\n }\n ]\n }\n ], \n \"metadata\": []\n}" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "" } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } }, "/orders": { "post": { "summary": "Report an order", "description": "", "operationId": "report-an-order", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "properties": { "id": { "type": "string", "description": "The order ID in the retailer's site. If not provided it is generated by CitrusAd in the response." }, "sessionId": { "type": "string", "description": "Unique sessionId used for attribution. Required to be consistent between a user's session and order reporting." }, "orderDate": { "type": "string", "description": "This is the date or the date and time of the order. This must be in the format of ISO-8601 RFC 3339 standard and must be a precise, full timestamp, e.g. 2019-03-14T15:06:17+10:00", "format": "date-time" }, "orderItems": { "type": "array", "items": { "properties": { "gtin": { "type": "string", "description": "The product code of the purchased product." }, "quantity": { "type": "integer", "description": "The quantity (units) of the product purchased.", "format": "int32" }, "regularUnitPrice": { "type": "string", "description": "This is regular unit price of the product in the order. If provided, it MUST be a number." }, "totalOrderItemPriceAfterDiscounts": { "type": "string", "description": "This is the total price of the products with discounts. It MUST be a number, e.g. if an order item contains 3 items with a price of 2.00, the value will be 6." }, "sellerId": { "type": "string", "description": "The unique Id of the seller. Only required if onboarding marketplace sellers. Can be left blank for non marketplace products. There are additional requirements to integrate seller_ids, please refer to [Marketplace sellerId](https://developers.citrusad.com/integration/reference/marketplace-sellerid) for more information." } }, "required": [ "gtin", "quantity", "totalOrderItemPriceAfterDiscounts" ], "type": "object" } } }, "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"orders\": [\n {\n \"adIds\": \"string\",\n \"teamId\": \"string\",\n \"customerId\": \"string\",\n \"sessionId\": \"string\",\n \"id\": \"string\",\n \"orderItems\": [\n {\n \"regularUnitPrice\": \"number\",\n \"citrusDiscountAmount\": \"number\",\n \"gtin\": \"string\",\n \"adId\": \"string\".\n \"quantity\": \"number\",\n \"substitutedFor\": \"string\",\n \"totalOrderItemPriceAfterDiscounts\": \"number\"\n }\n ],\n \"orderDate\": \"string\"\n }\n ]\n}" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false }, "get": { "summary": "Retrieve a list of orders", "description": "", "operationId": "retrieve-a-list-of-orders", "parameters": [ { "name": "teamId", "in": "query", "description": "If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "skip", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "orderIds", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "properties": { "id": { "type": "string", "description": "The order ID in the retailer's site. If not provided it is generated by CitrusAd in the response." }, "sessionId": { "type": "string", "description": "Unique sessionId used for attribution. Required to be consistent between a user's session and order reporting." }, "orderDate": { "type": "string", "description": "This is the date or the date and time of the order. This must be in the format of ISO-8601 RFC 3339 standard and must be a precise, full timestamp, e.g. 2019-03-14T15:06:17+10:00", "format": "date-time" }, "orderItems": { "type": "array", "items": { "properties": { "gtin": { "type": "string", "description": "The product code of the purchased product." }, "quantity": { "type": "integer", "description": "The quantity (units) of the product purchased.", "format": "int32" }, "regularUnitPrice": { "type": "string", "description": "This is regular unit price of the product in the order. If provided, it MUST be a number." }, "totalOrderItemPriceAfterDiscounts": { "type": "string", "description": "This is the total price of the products with discounts. It MUST be a number, e.g. if an order item contains 3 items with a price of 2.00, the value will be 6." }, "sellerId": { "type": "string", "description": "The unique Id of the seller. Only required if onboarding marketplace sellers. Can be left blank for non marketplace products. There are additional requirements to integrate seller_ids, please refer to [Marketplace sellerId](https://developers.citrusad.com/integration/reference/marketplace-sellerid) for more information." } }, "required": [ "gtin", "quantity", "totalOrderItemPriceAfterDiscounts" ], "type": "object" } } }, "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"orders\": [\n {\n \"adIds\": \"string\",\n \"teamId\": \"string\",\n \"customerId\": \"string\",\n \"sessionId\": \"string\",\n \"id\": \"string\",\n \"orderItems\": [\n {\n \"regularUnitPrice\": \"number\",\n \"citrusDiscountAmount\": \"number\",\n \"gtin\": \"string\",\n \"adId\": \"string\".\n \"quantity\": \"number\",\n \"substitutedFor\": \"string\",\n \"totalOrderItemPriceAfterDiscounts\": \"number\"\n }\n ],\n \"orderDate\": \"string\"\n }\n ]\n}" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } }, "/orders/{orderId}": { "get": { "summary": "Retrieve an order", "description": "", "operationId": "retrieve-an-order", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"adIds\": \"string\",\n \"teamId\": \"string\",\n \"customerId\": \"string\",\n \"sessionId\": \"string\",\n \"id\": \"string\",\n \"orderItems\": [\n {\n \"regularUnitPrice\": \"number\",\n \"citrusDiscountAmount\": \"number\",\n \"gtin\": \"string\",\n \"adId\": \"string\".\n \"quantity\": \"number\",\n \"substitutedFor\": \"string\",\n \"totalOrderItemPriceAfterDiscounts\": \"number\"\n }\n ],\n \"orderDate\": \"string\"\n}\n " } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } }, "/catalogs": { "post": { "summary": "Create or update a catalog", "description": "", "operationId": "create-or-update-a-catalog", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogs": { "type": "array", "items": { "properties": { "id": { "type": "string", "description": "Omit if creating a new catalogId." }, "teamId": { "type": "string" }, "name": { "type": "string", "description": "The name of the catalog" } }, "required": [ "name" ], "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"catalogs\": [\n {\n \"id\": \"string\",\n \"teamId\": \"string\",\n \"name\": \"string\"\n }\n ]\n}" } }, "schema": { "type": "object", "properties": { "catalogs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "string" }, "teamId": { "type": "string", "example": "string" }, "name": { "type": "string", "example": "string" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } }, "/catalog-products": { "post": { "summary": "Create or update a product", "description": "", "operationId": "create-or-update-a-product", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogProducts": { "type": "array", "items": { "properties": { "teamId": { "type": "string", "description": "Omittable. Can be derived from API Key." }, "catalogId": { "type": "string", "description": "The catalogId to synchronise the product within" }, "gtin": { "type": "string", "description": "The product code of the product. Does not need to be GTIN." }, "inventory": { "type": "integer", "description": "The number of the product in stock. If set to 0, product ads will not serve for the product.", "format": "int32" }, "price": { "type": "string", "description": "The number price of the product." }, "filters": { "type": "array", "description": "The filters/attributes of the products. Directly related to the productFilters specified in ad generation. This may be be category, location, and brand information.", "default": [], "items": { "type": "string" } }, "groups": { "type": "array", "description": "Used for category minimum bids and cross-sell placements. Contact your technical account manager to integrate these features.", "default": [], "items": { "type": "string" } }, "tags": { "type": "array", "description": "Used to specify imageurl and name used in the platform. Required in the format \"imageurl:\", \"name:\"", "default": [], "items": { "type": "string" } }, "sellerId": { "type": "string", "description": "The unique Id of the seller. Only required if onboarding marketplace sellers. Can be left blank for non marketplace products. One product required per product and sellerId combination. There are additional requirements to integrate seller_ids, please refer to [Marketplace sellerId](https://developers.citrusad.com/integration/reference/marketplace-sellerid) for more information." } }, "required": [ "catalogId", "gtin" ], "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "\n{\n \"catalogProducts\": [\n {\n \"teamId\": \"string\",\n \"catalogId\": \"string\",\n \"gtin\": \"string\",\n \"inventory\": \"number\",\n \"price\": \"number\",\n \"groups\": [\n \"string\"\n ],\n \"tags\": [\n \"string\"\n ],\n \"filters\": [\n \"string\"\n ],\n \"profit\": \"number\"\n }\n ]\n}" } }, "schema": { "type": "object", "properties": { "catalogProducts": { "type": "array", "items": { "type": "object", "properties": { "teamId": { "type": "string", "example": "string" }, "catalogId": { "type": "string", "example": "string" }, "gtin": { "type": "string", "example": "string" }, "inventory": { "type": "string", "example": "number" }, "price": { "type": "string", "example": "number" }, "groups": { "type": "array", "items": { "type": "string", "example": "string" } }, "tags": { "type": "array", "items": { "type": "string", "example": "string" } }, "filters": { "type": "array", "items": { "type": "string", "example": "string" } }, "profit": { "type": "string", "example": "number" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false }, "get": { "summary": "Retrieve a list of products", "description": "", "operationId": "retrieve-a-list-of-products", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum 1000", "schema": { "type": "integer", "format": "int32" } }, { "name": "skip", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "catalogId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "gtins", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "\n{\n \"catalogProducts\": [\n {\n \"teamId\": \"string\",\n \"catalogId\": \"string\",\n \"gtin\": \"string\",\n \"inventory\": \"number\",\n \"price\": \"number\",\n \"groups\": [\n \"string\"\n ],\n \"tags\": [\n \"string\"\n ],\n \"filters\": [\n \"string\"\n ],\n \"profit\": \"number\"\n }\n ]\n}" } }, "schema": { "type": "object", "properties": { "catalogProducts": { "type": "array", "items": { "type": "object", "properties": { "teamId": { "type": "string", "example": "string" }, "catalogId": { "type": "string", "example": "string" }, "gtin": { "type": "string", "example": "string" }, "inventory": { "type": "string", "example": "number" }, "price": { "type": "string", "example": "number" }, "groups": { "type": "array", "items": { "type": "string", "example": "string" } }, "tags": { "type": "array", "items": { "type": "string", "example": "string" } }, "filters": { "type": "array", "items": { "type": "string", "example": "string" } }, "profit": { "type": "string", "example": "number" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } }, "/catalog-products/{catalogId}/{gtin}": { "get": { "summary": "Retrieve a product", "description": "", "operationId": "retrieve-a-product", "parameters": [ { "name": "catalogId", "in": "path", "description": "The catalog you are retrieving the product within. Required.", "schema": { "type": "string" }, "required": true }, { "name": "gtin", "in": "path", "description": "The product code you are requesting. Does not need to be gtin. Required.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"teamId\": \"string\",\n \"catalogId\": \"string\",\n \"gtin\": \"string\",\n \"inventory\": \"number\",\n \"price\": \"number\",\n \"groups\": [\n \"string\"\n ],\n \"tags\": [\n \"string\"\n ],\n \"filters\": [\n \"string\"\n ],\n \"profit\": \"number\"\n}" } }, "schema": { "type": "object", "properties": { "teamId": { "type": "string", "example": "string" }, "catalogId": { "type": "string", "example": "string" }, "gtin": { "type": "string", "example": "string" }, "inventory": { "type": "string", "example": "number" }, "price": { "type": "string", "example": "number" }, "groups": { "type": "array", "items": { "type": "string", "example": "string" } }, "tags": { "type": "array", "items": { "type": "string", "example": "string" } }, "filters": { "type": "array", "items": { "type": "string", "example": "string" } }, "profit": { "type": "string", "example": "number" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } }, "/customers": { "post": { "summary": "Create or update a customer", "description": "", "operationId": "create-or-update-a-customer", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "properties": { "id": { "type": "string", "description": "The unique ID of the customer in your system." }, "teamId": { "type": "string", "description": "If a teamId is not provided, then the teamId will fall back onto the teamId provided by the API key." }, "yearOfBirth": { "type": "integer", "description": "Deprecated. Legacy field.", "format": "int32" }, "gender": { "type": "string", "description": "Deprecated. Legacy field.Accepted values: Male, Female, Other" }, "suburb": { "type": "string", "description": "Deprecated. Legacy field." }, "postcode": { "type": "string", "description": "Deprecated. Legacy field." }, "targetingData": { "type": "array", "description": "Deprecated. Legacy field.", "items": { "properties": { "key": { "type": "string", "description": "Arbitrary key:value pairing set by the retailer.", "default": "value" } }, "type": "object" } } }, "required": [ "id" ], "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"customers\": [\n {\n \"targetingData\": {\n \"string\": \"string\"\n },\n \"gender\": \"string\",\n \"teamId\": \"string\",\n \"postcode\": \"string\",\n \"suburb\": \"string\",\n \"id\": \"string, \n\t\t\t\t\t\"segmentIds\": [\n \"string\", \"string\"\n ],\n \"yearOfBirth\": \"integer\"\n }\n ]\n}\n" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false }, "get": { "summary": "Retrieve a list of customers", "description": "", "operationId": "retrieve-a-list-of-customers", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "skip", "in": "query", "schema": { "type": "string" } }, { "name": "customerIds", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "\n \"customers\": [\n { \n \"targetingData\": {\n \"string\": \"string\"\n },\n \"id\": \"string\",\n \"teamId\": \"string\",\n \"yearOfBirth\": \"integer\",\n \"gender\": \"string\",\n \"suburb\": \"string\",\n \"postcode\": \"string\",\n\t\t\t\t\t \"segmentIds\": [\n \"string\"\n ]\n\n }\n ]\n}" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } }, "/customers/{customerId}": { "get": { "summary": "Retrieve a customer", "description": "", "operationId": "retrieve-a-customer", "parameters": [ { "name": "customerId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{ \n \"targetingData\": {\n \"string\": \"string\"\n },\n \"id\": \"string\",\n \"teamId\": \"string\",\n \"yearOfBirth\": \"integer\",\n \"gender\": \"string\",\n \"suburb\": \"string\",\n \"postcode\": \"string\",\t\t\t\t\t\n\t\t\t\t\t\t \"segmentIds\": [\n \"string\"\n ]\n\n}" } }, "schema": { "type": "object", "properties": { "targetingData": { "type": "object", "properties": { "string": { "type": "string", "example": "string" } } }, "id": { "type": "string", "example": "string" }, "teamId": { "type": "string", "example": "string" }, "yearOfBirth": { "type": "string", "example": "integer" }, "gender": { "type": "string", "example": "string" }, "suburb": { "type": "string", "example": "string" }, "postcode": { "type": "string", "example": "string" }, "segmentIds": { "type": "array", "items": { "type": "string", "example": "string" } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } }, "/customers/manage-segments": { "post": { "summary": "Manage customer-segment linkage", "description": "", "operationId": "manage-customers-and-segments", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "teamId": { "type": "string", "description": "The retailer teamId for the retailer the customer is within." }, "customerId": { "type": "string", "description": "The unique identifier of the customer you are managing segments for." }, "segments": { "type": "array", "items": { "properties": { "segmentIds": { "type": "array", "description": "The list of Segment IDs the customer has access to.", "default": [], "items": { "type": "string" } } }, "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"additionalInfo\": [\n {\n \"code\": \"string\",\n \"message\": \"string\"\n }\n ],\n \"message\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "additionalInfo": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" } } } }, "message": { "type": "string", "example": "string" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "403": { "description": "403", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "404": { "description": "404", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "429", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "502": { "description": "502", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "503": { "description": "503", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "504": { "description": "504", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } } } }