openapi: 3.0.3 info: title: Loyal Guru Streaming Api description: >- # Introduction # Rate Limits All endpoints are classified into one of three tiers based on their computational complexity and usage frequency. The following RPS (requests per second) limits apply to all API keys: | Tier | Description | RPS | | --- | --- | --- | | **Tier 1 — Critical** | High-frequency, critical actions | 60 | | **Tier 2 — Moderate** | Moderate-frequency, supplementary actions | 25 | | **Tier 3 — Low** | Low-frequency, operational management | 10 | When a limit is exceeded, the API returns `HTTP 429 Too Many Requests` with a `Retry-After` header indicating how many seconds to wait before retrying. For full details on global caps, burst limits, and monthly usage, refer to your service agreement or contact your account manager. # HTTP API ## Http Responses An HTTP Response is composed by a **STATUS** and a **BODY** ( among other less important things.. ), keep in mind that should read both to have a complete understanding of what is happening. The STATUS is more important and the BODY will give you extra information. The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used. **Status** summary: - **200**: everything is ok. You may need to check the message with the 200 anyway in some cases to do certain thing. - **4xx**: you are not using our API properly. Check the message in the response body for more detail. - **5xx**: Our fault, Loyal Guru Api is having some error, report it to us please ## Errors ### Response Errors When a request is not success ( Response Status is not 200 ) the **Response Body** has this format: ``` { "error": "human readable error message", "code": "machine friendly error" } ``` When the error is related with API KEY validation the response error has this format: ``` { "message": "Forbidden" } ``` Every http's code the error means something different - **400** Your request is not correct, some parameter is required or is not in the right format. - **402** When a request is valid but does not complete successfully. - **403** The api key/secret are not valid. - **404** When the requested resource does not exist or cannot be found. - **500** Something when wrong with our server (These are rare.). We recommend to use **HTTP Response Status code** and **HTTP Response Body code field** to handle the errors. **Response Body error code field definitions** | code | meaning | |-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | *_not_found | The resource cannot be found. Example: customer_not_found | | forbidden_request | The resource you were trying to reach is absolutely forbidden | | invalid_request | The request is not valid, a parameters is missing or not valid | | server_error | Server error | |customer_not_enough_score | Customer haven't got enough scores for transferring | |customer_inactive | Customer is not active so no transfers can be executed | | voucher_redeemed | The voucher is already redeemed | | voucher_expired | The available_to date is earlier than today | | voucher_inactive | The coupons is not active | | voucher_deleted | The coupon has been deleted | | voucher_out_location | The voucher cannot be redeemed in the current location | | voucher_out_date | The available_from date is later than today | | voucher_not_found | The voucher not found, customer not found or voucher does not belong to customer | | exchange_not_found | The score exchange is not found for the required location | #### Server errors In case of server_error or unexpected error the Application is responsible for waiting for a period of time before issuing another request. This means that after the first error, there is a minimum back-off interval of 1 second and for each consecutive error, the back-off interval increases exponentially up to 32 seconds. ## Types As this is a http API the "real types" that you can use are the types that allows you to send the http protocol as a parameter, these are **number**, **string**, **boolean** and **array**. So you'll see this 4 types specified along the docs in the request and response parameters of every method, but please keep in mind that your should follow this format guide. - **(Number) Integer**: ```123``` Length from 1 to 9223372036854775807 - **(Number) Float**: ```123.45``` Decimal separator is dot, not coma. - **(String)**: ```hello``` - **(String) Date**: ```2016-12-31``` - **(String) DateTime**: ```2016-12-31T23:59:43Z``` - **(Boolean)**: ```true``` or ```false``` - **(Array)**: ```[{"key1":123,"key2":"hello","key3":"2016-12-31T23:59:43Z"}]``` - **(slug)**: ( not a proper type but.. ) A short label for something, containing only letters, numbers, underscores or hyphens. ```sub_family``` **Important notes**: - **Date and DateTime: you MUST ensure that you use ISO-8601 date format in UTC**, so it's possible that you'll need to apply some kind of conversion to your date ( and UTC will be returned in the API ) ([some documentation related](http://apiux.com/2013/03/20/5-laws-api-dates-and-times/)). If you are not able to send UTC you should specify the offset of your DateTime ( ```2016-12-31T23:59:43-0500``` ), keep in mind that the offset is different depending on your timezone and date. - **Regarding to the Integer type**: ```0``` is not a valid integer - **Regarding to the Integer type**: ```00X``` will be converted to ```X``` so keep in mind this if you have, for example, in your database situations in which ```003``` is the id of a certain resource and ```3``` is the id of another different resource, for us ```003``` and ```3``` is the same number.To avoid collisions between the real 001 and the real 1 in your database. For this purpose you could solve the problem by always adding to parameter a ```1``` prefix so the end result is ```1001``` and ```11``` and no collision between ```001``` converted to ```1``` and the real ```1``` will be existing - Text encoding: utf-8 - Along the documentation we are not specifying DateTime or Float. You'll only see it by the example on the param. If the integer can be float you'll se an example with a float and if the Date should be a DateTime you'll see an example with a DateTime instead of a Date. ## Email Header An Email header can be provided in the API requests. This email parameter will be used to register the authors of the request for a set of specific endpoints. At this moment the endpoints that register the author are: - POST /scores/transfer - POST /scores/trigger ## Internationalization After user authentication you can specify the expected language to our API (as part of the http-headers) in order to force the language in which the system will respond to some of the endpoints regarding multi-language content ( for example: coupons, vouchers, rewards, score transactions, challenges). Please notice that if no language is declared in the header, the system will return the default values. **This only applies to companies with multilanguage feature enabled** ``` Accept-Language: 'en' ``` if "Accept-Language" in header: if "Accept-Language" language is included as part of the possible options: return text in language of the header else: return text in default language of the company else: return default values for multilanguage fields. Ex: English nameNombre en español ## Idempotent Requests The API supports idempotence for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to subtract scores fails due to a network connection error, you can retry the request with the same idempotence key to guarantee that only a single subtract is done. Note that retrying a request with an idempotence key will not change the outcome of a request. When the API receives a request successfully but returns an error code, retrying it with an idempotence key will simply result in a new response with the same error code. GET and DELETE requests are idempotent by definition, meaning that the same backend work will occur no matter how many times the same request is issued. You shouldn't send an idempotence key with these verbs because it will have no effect. To perform an idempotent request, provide an additional Idempotency-Key: header to the request. How you create unique keys is up to you, but we suggest using V4 UUIDs or another appropriately random string. We'll always send back the same response for requests made with the same key, and keys can't be reused with different request parameters. Keys expire after 24 hours. ``` Idempotency-Key: 'QknyRdIN6wECfOb5' ``` # Postman tool We recommend you Postman in order to freely try this API. It's a great tool, easy to use, and you'll be able to issue every call to our API. Remember to set properly your headers. Download Postman # Domain Entities ## Resources - Main resources The main resources you'll be able to manage with this API are: - **Customers** - **Customer events** - **Carts** (LEGACY Activities): Purchase tickets with line detail and used vouchers and applied promotions - **Custom Events** - **Triggers** - **Loyalty & Gamification campaigns** - **Discount**: Discount campaign that define how to discount a cart - **Points** (LEGACY scores): Point campaigns that define how to accumulate points - **Rewards**: Related to rewards that can by redeemed using scores, etc.. - **Challenges**: Related to challenges that can by won by customers, etc.. - **Campaign Coupons**: coupons associated to a discount campaign ( or a points, reward campaign ) - **Campaigns Vouchers**: Association between a customer and a coupon - **Company Data** - **Products**: Your merchandise - **Product Taxonomies**: The different categorization levels of your products - **Product Features**: The different values of a certain categorization level - **Locations**: Your different locations / shops / centers, etc.. - **Location Taxonomies**: The different categorization levels of your locations - **Location Features**: The different values of a certain categorization level - **Promotions** LEGACY: Generic discounts ### Product taxonomy system Regarding the product taxonomy system, here you'll see and example of how to represent a categorization of products in our flexible system. ``` +-- Taxonomy ( Family ) | +-- Feature ( Meat ) | +-- Product ( Ham ) | +-- Product ( Cow ) | +-- Product ( Horse ) | +-- ... | +-- Feature ( Vegetables ) | +-- Product ( Tomato ) | +-- ... | +-- Feature ( Drinks ) | +-- Product ( Coca-cola ) | +-- ... | +-- ... +-- Taxonomy ( Sub-Family ) | +-- Feature ( Soda ) | +-- Product ( Coca-cola ) | +-- ... | +-- ... +-- Taxonomy ( Section ) +-- ... ``` ## Understanding Activities, Lines and cancellations Check please the documentation of the method create activity below to have a good understanding of how a purchase activity works ( discounts, cancellations , negative and positive values... ) # API Tips and recommendations ## Pagination Some of our top resources have support for bulk fetches via "list" API methods. For instance, you can list score transactions or list of vouchers. These list API methods share a common structure with the parameter parameters: starting_after. Loyal Guru utilizes cursor-based pagination via the starting_after parameter. You must use the response body parameter `next_token_starts_after` as `starting_after` parameter to the next to get the next page. If the current page is the last `next_token_starts_after` is not present. The order of the elements in the list could change between endpoints. ## PUT as an alternative for PATCH If your library doesn't support the use of a PATCH method you can always use a PUT method instead. We strongly recommend the use of the PATCH method as the standard for this kind of actions, but we provide this alternative for older libraries. # Security ## Authentication Every call must use these three authentication headers: ``` X-Api-Key: api_key X-Api-Secret: api_key_secret X-Api-Version: 1 ``` Please, keep in mind that you must respect Lower and Uppercase characters in the header variable name. The api_key and the api_key_secret will be delivered by Loyal Guru, ask for them if you don't have them at info@loyal.guru. ## Duplication For security reasons our system ignores all duplicated calls (same content and action) to update/delete/create elements within a 5-minutes interval. ## ID Integrity We use the ID field of the records to avoid duplication and keep the integrity of the system. When you execute any action over a record the ID will be checked: - Insert a record with an ID that already exists will raise in real time ( not deferred ) a request error. - Delete a record with an ID than does not exist will raise in real time ( not deferred ) a request error. Exceptions: - Activities: ID will no be checked in "POST Activities" ( it will be checked in "POST Activities/RealTime" ), so if a duplicated activity is sent will raise a **deferred** error and not a real time one. - Customers: apart form ID the email will also be checked. contact: {} version: '1.0' license: name: Loyal Guru url: https://www.loyal.guru/legal-disclaimer/ x-logo: url: >- https://firebasestorage.googleapis.com/v0/b/lg-api-docs.appspot.com/o/logo-loyal-guru.png?alt=media&token=f1ea3ba3-04ab-4ff3-9f6c-88ea73225168 backgroundColor: '#FFFFFF' altText: Loyal Guru servers: - url: https://streaming.loyal.guru variables: {} tags: - name: cashbacks description: Cashbacks - name: cashback thresholds description: >- The cashback threshold is the minimum score value to allow a customer to ask for cashback. - name: check description: Checks - name: custom events description: Custom Events - name: customers description: Customers - name: associations & merges description: Associations & Merges - name: carts description: Carts - name: locations description: Locations - name: location taxonomies description: Locations taxonomies - name: location features description: Locations features - name: campaign coupons description: Campaign - Coupons - name: promotions description: Promotions - name: messages description: Messages - name: vouchers description: Vouchers - name: products description: Products - name: product taxonomies description: Product Taxonomies - name: product features description: Product Features - name: triggers description: Triggers - name: rewards description: Rewards - name: redemptions description: Redemptions - name: challenges description: Challenges - name: tiers, attributes & audiences description: Tiers, Attributes & Audiences - name: discounts description: Discounts - name: Games x-displayName: Games description: Game campaigns and participation gameplay endpoints. - name: points & wallet description: Points & Wallet - name: campaign vouchers description: Campaign Vouchers - name: simulate a cart description: Simulate a Cart - name: create a cart description: Create a Cart - name: create a custom event description: Create a Custom Event - name: process a trigger for a specific customer description: Process a trigger for a specific customer paths: /customers: post: tags: - customers - refer a friend summary: Create a New Customer description: >- To create a customer using the friend referral feature, check the referred_by field in the request body schema description. **Important**: The `updated_at` field is automatically set to the current server time when creating a customer, regardless of any `creation_date` value provided. This ensures accurate tracking of when records are processed by the server. **Tier 2 (Moderate)** — See rate limit table operationId: CreateANewCustomer parameters: - name: allow_duplicate_email in: query description: >- Allows to create a customer with existing email. Duplicated email will be stored in duplicated_email field. If not received, default value is 'false'. style: form explode: true schema: type: boolean example: false - name: allow_duplicate_dni in: query description: >- Allows to create a customer with existing dni. Duplicated dni will be stored in duplicated_dni field. If not received, default value is 'false'. style: form explode: true schema: type: boolean example: false requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewCustomerrequest' - example: id: 1234 code: A54fTr1 name: Jon surname_1: Snow surname_2: Sand email: jon@winter.com phone: '678123456' phone_prefix: '34' address: Snow Tree address_extra: 31 1 postal_code: '08110' birth: '2016-01-01' gender: feminine document_type: dni dni: 53023040B country: ES authentication_token: y78rhr29feuyfw89 registration_location_id: 123 registration_location_code: loc_cod_001 status: active password: mysecretpassword password_confirmation: mysecretpassword creation_date: '2016-01-01T20:23:20Z' sms_unsubscribe: true email_unsubscribe: true push_unsubscribe: true paper_free: false collective_id: 17 collective_slug: employees communications: true terms: true profiling: true terms_accepted_at: '2016-01-02T15:04:05Z' profiling_accepted_at: '2016-01-02T15:04:05Z' app: false push_token: cd9fea48-c2c4-ab88-d4ef-db1f7288af92 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 custom9: custom value 9 custom10: custom value 10 custom11: custom value 11 kind: ecommerce preferred_language: es referred_by: 1234 fraudulent: false third_party_consent: true attributes: loyalty_tier: gold customer_score: 850 newsletter_opt_in: true tags: - vip - premium - early_adopter preferred_store_ids: - 101 - 205 - 308 interests: - electronics - fashion - sports example: id: 1234 code: A54fTr1 name: Jon surname_1: Snow surname_2: Sand email: jon@winter.com phone: '678123456' phone_prefix: '34' address: Snow Tree address_extra: 31 1 postal_code: '08110' birth: '2016-01-01' gender: feminine document_type: dni dni: 53023040B country: ES authentication_token: y78rhr29feuyfw89 registration_location_id: 123 status: active password: mysecretpassword password_confirmation: mysecretpassword creation_date: '2016-01-01T20:23:20Z' sms_unsubscribe: true email_unsubscribe: true push_unsubscribe: true paper_free: false collective_id: 17 collective_slug: employees communications: true terms: true profiling: true terms_accepted_at: '2016-01-02T15:04:05Z' profiling_accepted_at: '2016-01-02T15:04:05Z' app: false push_token: cd9fea48-c2c4-ab88-d4ef-db1f7288af92 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 custom9: custom value 9 custom10: custom value 10 custom11: custom value 11 kind: ecommerce preferred_language: es referred_by: 1234 fraudulent: false third_party_consent: true attributes: loyalty_tier: gold customer_score: 850 newsletter_opt_in: true tags: - vip - premium - early_adopter preferred_store_ids: - 101 - 205 - 308 interests: - electronics - fashion - sports required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false get: tags: - customers security: - api_key: [] summary: Get a list of customers description: >- Get a list of customers, filtered by ID and/or phone number. Usage of the parameters: - `ids` or `phones` must be present to get the list of customers. Otherwise, the API returns an error. - `ids` and `phones` can be sent at the same time. **Tier 3 (Low)** — See rate limit table operationId: GetAListOfCustomers parameters: - name: ids in: query description: >- List of IDs to be used for filtering. If there are more than one, they should be separated by commas. schema: type: string example: 123,456 - name: phones in: query description: >- List of phone numbers to be used for filtering. If there are more than one, they should be separated by commas. schema: type: string example: 666777888,666777999 responses: '200': description: >- Look the example below to be aware of all information returned per customer. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetAListOfCustomersResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: code: invalid_request error: error message example: code: invalid_request error: error message '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message /customers/search: post: tags: - customers summary: Search customers by any field description: >- The field and value to look for in the body of the POST request. The fields that can be searched are: id, code, dni, associate_id, email. **Tier 3 (Low)** — See rate limit table operationId: SearchByCustomers parameters: [] requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/Searchcustomersrequest' examples: search by id: summary: Search by ID. value: id: 123 search by code: summary: Search by Code. value: code: some_code search by dni: summary: Search by DNI. value: dni: 00000000T search by associate_id: summary: Search by Associate ID. value: associate_id: 123 search by email: summary: Search by Email. value: email: email@email.com required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getcustomerresponse' - example: id: 123 code: A54fTr1 dni: 00000000T name: Jon surname_1: Snow surname_2: Sand email: jon@example.com birth: '1985-06-15' phone_prefix: '+1' phone: '555123456' status: active address: 123 Main Street address_extra: Apt 4B postal_code: '10001' city: New York state: NY trimestral_expend: 123 score: 100 score_available: 80 paper_free: true merged: true merged_to: 321 kind: ecommerce preferred_language: es communications: true app: false registration_location_id: 5678 registration_location_code: NYC-Downtown fraudulent: false collective_id: 456 attributes: search_verified: true engagement_score: 95 example: id: 123 code: A54fTr1 dni: 00000000T name: Jon surname_1: Snow surname_2: Sand email: jon@example.com birth: '1985-06-15' phone_prefix: '+1' phone: '555123456' status: active address: 123 Main Street address_extra: Apt 4B postal_code: '10001' city: New York state: NY trimestral_expend: 123 score: 100 score_available: 80 paper_free: true merged: true merged_to: 321 kind: ecommerce preferred_language: es communications: true app: false registration_location_id: 5678 registration_location_code: NYC-Downtown fraudulent: false collective_id: 456 attributes: search_verified: true engagement_score: 95 '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the customer is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the customer is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /customers/{value}: get: tags: - customers summary: Get customer description: '**Tier 1 (Critical)** — See rate limit table' operationId: GetCustomer parameters: - name: value in: path description: >- Could be an integer or a string. Search options are as follows: - ID: Its the default behavior and `search_param` can be optionally specified with **id**. An integer value is required. - Code: `search_param` must be specified with **code**. A string value is required. - DNI: `search_param` must be specified with **dni**. A string value is required. - Email: `search_param` must be specified with **email**. A string value is required. required: true style: simple schema: type: string example: 1234,53345345B - name: search_param in: query description: The param field used for the customer search. required: true schema: type: string example: id,code,dni,email responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getcustomerresponse' - example: id: '123' code: A54fTr1 name: Jon surname_1: Snow surname_2: Sand email: jon@example.com trimestral_expend: 123 score: 100 score_available: 80 paper_free: true merged: true merged_to: 321 kind: ecommerce preferred_language: es communications: true app: false dni: 12345678Z birth: '1990-12-31' custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom8: custom 8 value custom9: custom 9 value custom1f: custom 1f value custom2f: custom 2f value custom3f: custom 3f value custom4f: custom 4f value custom5f: custom 5f value custom6f: custom 6f value custom7f: custom 7f value custom8f: custom 8f value phone: '600600600' phone_prefix: '+34' address: Calle ABC, 10 address_extra: '-' postal_code: '55555' city: Barcelona state: Catalonia status: active registration_location_id: 1234 registration_location_code: S22C-Plaza fraudulent: false attributes: loyalty_tier: gold customer_score: 850 vip_status: true example: id: '123' code: A54fTr1 name: Jon surname_1: Snow surname_2: Sand email: jon@example.com phone_prefix: '+34' phone: '600600600' address: Calle ABC, 10 address_extra: '-' postal_code: '55555' city: Barcelona state: Catalonia trimestral_expend: 123 score: 100 score_available: 80 paper_free: true merged: true merged_to: 321 kind: ecommerce preferred_language: es communications: true app: false dni: 12345678Z birth: '1990-12-31' custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom8: custom 8 value custom9: custom 9 value custom10: custom 10 value custom11: custom 11 value custom1f: custom 1f value custom2f: custom 2f value custom3f: custom 3f value custom4f: custom 4f value custom5f: custom 5f value custom6f: custom 6f value custom7f: custom 7f value custom8f: custom 8f value status: active registration_location_id: 1234 registration_location_code: S22C-Plaza fraudulent: false collective_id: 123 third_party_consent: true attributes: loyalty_tier: gold customer_score: 850 vip_status: true '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the customer is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the customer is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false patch: tags: - customers summary: Update a Customer description: >- **Important**: The `updated_at` field in the request body is now deprecated and ignored. The system automatically sets `updated_at` to the current server time for all customer updates. This ensures data consistency and accurate tracking of record modifications for downstream systems. **Attributes Validation**: For the `attributes` field, only the incoming attributes in your request are validated against the schema. Existing attributes stored on the customer are NOT re-validated. This means: - Schema changes (e.g., removing an enum value) won't break updates to existing customers - Old values remain until explicitly updated or deleted - New values being set must comply with the current schema **Tier 2 (Moderate)** — See rate limit table operationId: UpdateACustomer parameters: - name: value in: path description: >- Could be an integer or a string. - If it is an integer, the system will search the customer by its **id**. - If it is a string, the system will search the customer by **code**. In this case `search_param` must be specified with **code**. required: true style: simple schema: type: integer format: int64 - name: search_param in: query description: 'Field used to update customer. Valid fields: (id, code)' style: form explode: true schema: type: string example: id - name: allow_duplicate_email in: query description: >- Allows to update a customer with existing email. Duplicated email will be stored in duplicated_email field. If not received, default value is 'false'. style: form explode: true schema: type: boolean example: false - name: allow_duplicate_dni in: query description: >- Allows to update a customer with existing dni. Duplicated dni will be stored in duplicated_dni field. If not received, default value is 'false'. style: form explode: true schema: type: boolean example: false requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaCustomerrequest' - example: name: Jon surname_1: Snow surname_2: Sand email: jon@winter.com phone: '678123456' phone_prefix: '34' address: Snow Tree address_extra: 31 1 postal_code: '08110' birth: '2016-01-01' gender: feminine document_type: dni dni: 53023040B country: ES authentication_token: y78rhr29feuyfw89 registration_location_id: 123 registration_location_code: loc_cod_001 usual_location_id: 123 status: active creation_date: '2016-01-01T20:23:20Z' sms_unsubscribe: true email_unsubscribe: true push_unsubscribe: true paper_free: false collective_id: 17 collective_slug: employees communications: true terms: true profiling: true terms_accepted_at: '2016-01-02T15:04:05Z' profiling_accepted_at: '2016-01-02T15:04:05Z' app: false push_token: cd9fea48-c2c4-ab88-d4ef-db1f7288af92 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 custom9: custom value 9 custom10: custom value 10 custom11: custom value 11 kind: ecommerce preferred_language: es fraudulent: false attributes: loyalty_tier: gold customer_score: 850 newsletter_opt_in: true tags: - vip - premium - early_adopter preferred_store_ids: - 101 - 205 - 308 interests: - electronics - fashion - sports example: name: Jon surname_1: Snow surname_2: Sand email: jon@winter.com phone: '678123456' phone_prefix: '34' address: Snow Tree address_extra: 31 1 postal_code: '08110' birth: '2016-01-01' gender: feminine document_type: dni dni: 53023040B country: ES authentication_token: y78rhr29feuyfw89 registration_location_id: 123 registration_location_code: loc_cod_001 usual_location_id: 123 status: active creation_date: '2016-01-01T20:23:20Z' sms_unsubscribe: true email_unsubscribe: true push_unsubscribe: true paper_free: false collective_id: 17 collective_slug: employees communications: true terms: true profiling: true terms_accepted_at: '2016-01-02T15:04:05Z' profiling_accepted_at: '2016-01-02T15:04:05Z' app: false push_token: cd9fea48-c2c4-ab88-d4ef-db1f7288af92 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 custom9: custom value 9 custom10: custom value 10 custom11: custom value 11 kind: ecommerce preferred_language: es fraudulent: false attributes: loyalty_tier: gold customer_score: 850 newsletter_opt_in: true tags: - vip - premium - early_adopter preferred_store_ids: - 101 - 205 - 308 interests: - electronics - fashion - sports required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - customers summary: Delete a customer description: >- Deletes a customer definitely or empty it according to the 'hard' variable There are two delete modes according to the 'hard' variable If the 'hard' variable is true, it will execute the hard delete mode. - This mode deletes definitely the customer if he/she hasn't any critical relation. The critical relations are: · activities · cashback · redemptions · score transactions · tag customers · vouchers If the customer have critical relations, is not possible to do the hard delete but the soft delete will be done Otherwise if the 'hard' variable is false, it will execute the soft delete mode. - This mode empty the customer and deletes some relations with them. The customer still exists so the id is not possible to use in other customer. **Important**: A customer cannot be deleted while in "merging" status. If a delete request is made for a customer with status "merging", the API will return a 409 CONFLICT error. **Tier 3 (Low)** — See rate limit table operationId: DeleteACustomer parameters: - name: value in: path description: ID of the customer required: true style: simple schema: type: integer format: int64 or string example: 12 - name: hard in: query description: Defines the hard mode required: true style: form explode: true schema: type: boolean example: true - name: search_param in: query description: 'Field used to update customer. Valid fields: (id, code)' style: form explode: true schema: type: string example: id - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Deleteacustomerresponse' - example: status: success example: status: success '400': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Deleteacustomerresponse1' - example: code: invalid_request error: Error message example: code: invalid_request error: Error message '409': description: Customer cannot be deleted while in merging state. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/NumericError' - description: Customer cannot be deleted while in merging state. example: code: 63000 error: Customer cannot be deleted while in merging state. company: public example: code: 63000 error: Customer cannot be deleted while in merging state. company: public deprecated: false /customers/{id}/attributes: get: tags: - tiers, attributes & audiences summary: Retrieve the calculated attributes for a specific customer description: |- Get the list of customer attributes for a customer **Tier 3 (Low)** — See rate limit table operationId: GetAListOfCustomerAttributesFromACustomer parameters: - name: id in: path description: Id of the customer required: true schema: type: integer format: int64 example: - 123 - name: attribute_type in: query description: >- Attribute type of the customer attribute to list. Mutually exclusive with attribute_id. style: form explode: true schema: type: string example: - calculation - name: attribute_id in: query description: >- Attribute definition id of the customer attribute to list. Mutually exclusive with attribute_type. schema: type: integer format: int64 example: - 3214 - name: name in: query description: >- Name to search the customer attribute list. It's not case-sensitive and does not require an exact match. schema: type: string example: - attr - name: system in: query description: Define system to search the customer attribute list. schema: type: boolean example: true - name: per_page in: query description: 'Max number of attributes returned per response. - Default: 10' style: form explode: true schema: type: integer format: int64 example: 20 - name: starting_after in: query description: >- Yo will receive this token on every response ( on the variable **next_token_starts_after** ) in order to have the next batch of elements. style: form explode: true schema: type: string example: token responses: '200': description: Array will contain all found customers attribute. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getalistofcustomerattributesresponse' - example: data: - name: Max cost value: '50.6' data_type: float attribute_type: calculation slug: max_cost system: true created_at: '2018-09-04T16:19:25.343+02:00' next_token_starts_after: token '400': description: When the parameters are invalid. headers: {} content: application/json: schema: allOf: - $ref: >- #/components/schemas/Getalistofcustomerattributeresponseerrormut - description: When the paramteres are mutually exclusive. example: error: attribute_type and attribute_id are mutually exclusive code: invalid_request '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: >- #/components/schemas/Getalistofcustomerattributeresponseerror - description: Server error, try again and contact with support. example: error: Internal server error deprecated: false parameters: [] /customers/{id}/tiers: get: tags: - tiers, attributes & audiences summary: Retrieve the loyalty tiers for a specific customer description: >- Retrieve an array of all active program tiers related to the customer. This includes program tiers specific to the customer's country and those not assigned to any country (program tiers available for the entire customer database). **Only program tiers relevant to the customer's country and currently active will be included in the response.** Check out the following links that can help you: - How to build a tier level progress bar: [Link](https://loyal-guru.atlassian.net/servicedesk/customer/portal/9/topic/b5340838-0aa1-4816-b558-6e4680d51328/article/3026845697) - How to create a loyalty tiered program: [Link](https://loyal-guru.atlassian.net/servicedesk/customer/portal/9/topic/b5340838-0aa1-4816-b558-6e4680d51328/article/2545123350) **Tier 3 (Low)** — See rate limit table operationId: GetAListOfTiers parameters: - name: id in: path description: |- Could be an integer or a string. - If `search_param` is specified with **code** and is a valid string value, the system will search the customer by **code**. - If it is an integer, the system will search the customer by its **id**. schema: type: integer style: simple - name: search_param in: query description: |- The param field used for the customer search. Possible options: "id" and "code" schema: type: string default: id example: code responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/GetAListOfTiersResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /customers/{id}/audience_validation: get: tags: - tiers, attributes & audiences security: - api_key: [] summary: Check if a customer belongs to a specific audience description: >-
The endpoint /customers/{id}/segment_validation is also available as a LEGACY version of this API.
Get the result of checking if a customer belongs to a segment **Tier 3 (Low)** — See rate limit table operationId: Customers_GetSegmentValidation parameters: - name: id in: path description: '' required: true style: simple schema: type: string - name: segment_id in: query description: The segment ID required: true schema: type: integer format: int64 example: 1234 responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomersGetSegmentValidationResponse' '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: |- Semantics issues Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: |- Semantics issues Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code /customers/{id}/audiences: get: tags: - tiers, attributes & audiences security: - api_key: [] summary: Retrieve all audiences for a specific customer description: >-
The endpoint /customers/{id}/segments is also available as a LEGACY version of this API.
Get the list of segments which the customer belongs to. **Tier 3 (Low)** — See rate limit table operationId: Customers_GetSegments parameters: - name: id in: path description: '' required: true style: simple schema: type: string responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomersGetListOfSegmentsResponse' '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: |- Semantics issues Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: |- Semantics issues Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code /associations: post: tags: - associations & merges summary: Create an Association description: '**Tier 3 (Low)** — See rate limit table' operationId: CreateANewAssociation parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewAssociationrequest' - example: customer_id: 1234 associate_customer_id: 4321 relationship_type: default active: true main: true example: customer_id: 1234 associate_customer_id: 4321 relationship_type: default active: true main: true required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewAssociationresponse' - example: id: 1 customer_id: 1234 associate_customer_id: 4321 relationship_type: default active: true main: true created_at: '2021-09-22T14:02:06.708121Z' updated_at: '2021-09-22T14:02:06.708121Z' example: id: 1 customer_id: 1234 associate_customer_id: 4321 relationship_type: default active: true main: true created_at: '2021-09-22T14:02:06.708121Z' updated_at: '2021-09-22T14:02:06.708121Z' '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false patch: tags: - associations & merges summary: Update an Association description: >- Updates the relationship type of the active association between provided customers. **Tier 3 (Low)** — See rate limit table operationId: UpdateAnAssociation parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateanAssociationrequest' - example: customer_id: 1234 associate_customer_id: 4321 relationship_type: default main: true example: customer_id: 1234 associate_customer_id: 4321 relationship_type: default main: true required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - associations & merges summary: Delete an Association description: |- Sets as inactive the active association between provided customers. **Tier 3 (Low)** — See rate limit table operationId: DeleteAnAssociation parameters: - name: customer_id in: query description: ID of the customer in form of an integer. required: true schema: type: integer format: int64 example: 1234 - name: associate_customer_id in: query description: ID of the associate customer in form of an integer. required: true schema: type: integer format: int64 example: 4321 - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /customers/{id}/associates: get: tags: - associations & merges summary: Get a list of Association description: '**Tier 3 (Low)** — See rate limit table' operationId: GetAListOfAssociates parameters: - name: active in: query description: >- Status of the association between the customer and the associates to list. If not provided, it will be true by default. required: true schema: type: boolean example: true - name: id in: path description: '' required: true style: simple schema: type: string - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getalistofassociatesresponse' - example: list: - id: 1 customer_id: 999050031793530 associate_customer_id: 999050032283499 relationship_type: null active: true created_at: '2021-09-22T10:45:32.40923Z' updated_at: '2021-09-22T10:45:32.40923Z' - id: 2 customer_id: 999050031793530 associate_customer_id: 999050032283689 relationship_type: merge active: true merge_id: 1 created_at: '2021-09-22T14:02:06.708121Z' updated_at: '2021-09-22T14:02:06.708121Z' main: true example: list: - id: 1 customer_id: 999050031793530 associate_customer_id: 999050032283499 relationship_type: null active: true created_at: '2021-09-22T10:45:32.40923Z' updated_at: '2021-09-22T10:45:32.40923Z' - id: 2 customer_id: 999050031793530 associate_customer_id: 999050032283689 relationship_type: merge active: true merge_id: 1 created_at: '2021-09-22T14:02:06.708121Z' updated_at: '2021-09-22T14:02:06.708121Z' main: true '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: |- Semantics issues Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: |- Semantics issues Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /customers/{id}/cards: post: tags: - associations & merges summary: Create new card associated to customer description: |- Create a new card associated to a customer **Tier 3 (Low)** — See rate limit table operationId: CreateANewCardAssociatedToACustomer security: - httpBasic: [] - api_key: [] parameters: - name: id in: path description: ID of the customer required: true schema: type: integer requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewCardassociatedtoaCustomer' - example: - id: 331 main: true motive: default relationship_type: default example: id: 331 main: true motive: default relationship_type: default required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false parameters: [] /customers/transfer: post: tags: - associations & merges summary: Merge one customer into another description: >- Executes a merge between two customers. This is the detailed actions done during a merge operation: - set the old customer's status to "merging" immediately (protects against deletion during merge) - create an associate record related to both customers - reassign all associated records to the new customer. Entities involved: activities, campaign_content_customers, cashbacks, loyalty_score_vouchers, redemptions, relatives, scores, score_expenses, score_transactions, vouchers - set the old customer as the associated in all the transferred activities - set the old customer's status to "merged" so it cannot be targeted by segments Personal data (such as name, phone number, email...) is not transferred nor erased in the old customer. New customer keeps all previous associated records they had. The merge operation is just 'appending' data to them. **Status Flow**: active/inactive → merging → merged The transference won't take place when: - the old customer is already merged or merging - the new customer is already merged **Tier 3 (Low)** — See rate limit table operationId: MergeDataBetweenCustomers parameters: [] requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/Mergedatabetweencustomersrequest' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Mergedatabetweencustomersresponse' - example: status: success example: status: success '400': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Mergedatabetweencustomersresponse1' - example: code: invalid_request error: Error message example: code: invalid_request error: Error message '409': description: One of the customers has a merge or unmerge operation in progress. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: >- Merge/unmerge operation in progress for one of the customers. example: code: datatransfer_running error: >- one of the customers in the request has a merge or unmerge running try again later example: code: datatransfer_running error: >- one of the customers in the request has a merge or unmerge running try again later deprecated: false /customers/{associate_id}/unmerge: post: tags: - associations & merges summary: Unmerge one customer from another description: >- Breaks customer association with its parent one. Only customers with not empty "merged_to" field can be unmerged. - Set association "active" field to false. - Create a record in customer_merge_logs with unmerge information using association merge_id field as an origin_merge_id - Change associated customer status field to active - Unset merge_to field fron associated customer. - If with_activites flag is set to true, all the activities that were transferred to the parent will be reassigned to the associate, otherwise they will be kept in the parent customer. **Tier 3 (Low)** — See rate limit table operationId: UnmergeCustomerFromItsParentOne parameters: - name: associate_id in: path description: >- ID of the customer in form of an integer. If sent a string and `search_param` is specified with **code**, the system will search the customer by **code** required: true style: simple schema: type: integer format: int64 example: 1234 - name: with_activites in: query description: >- Flag for indicating if activities must be reassigned to the associate or kept in the parent customer. Default: `false` required: true schema: type: boolean example: true - name: search_param in: query description: >- The param field used for the customer search. In case it is not present or invalid, the default value will be **id**. required: false schema: type: string example: id,code - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: >- #/components/schemas/Unmergecustomerfromitsparentoneresponse - example: status: success example: status: success '400': description: '' headers: {} content: application/json: schema: allOf: - $ref: >- #/components/schemas/Unmergecustomerfromitsparentoneresponse1 - example: code: invalid_request company: loyal-guru error: Error message example: code: invalid_request company: loyal-guru error: Error message '409': description: The customer has a merge or unmerge operation in progress. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: company: type: string description: Company slug where the error occurred description: Merge/unmerge operation in progress for the customer. example: code: datatransfer_running error: >- one of the customers in the request has a merge or unmerge running try again later company: loyal-guru example: code: datatransfer_running error: >- one of the customers in the request has a merge or unmerge running try again later company: loyal-guru deprecated: false /customers/transfer-new: post: tags: - associations & merges summary: Merge by creating a new customer with the data of the other customer description: |- Transfers the data related to a customer to a newly created customer. The old customer's status is set to "merging" immediately when the request is received, protecting it from deletion during the merge process. Once the merge completes (asynchronously), the status is set to "merged". **Status Flow**: active/inactive → merging → merged The transference won't take place when: - the old customer is already merged or merging - there is an active association between the customers **Tier 3 (Low)** — See rate limit table operationId: CreateANewCustomerWithTheDataOfTheOtherCustomer parameters: - name: X-Api-Key in: header description: '' required: true style: simple schema: enum: - api_key type: string example: api_key - name: X-Api-Secret in: header description: '' required: true style: simple schema: enum: - api_key_secret type: string example: api_key_secret - name: X-Api-Version in: header description: '' required: true style: simple schema: enum: - '1' type: string example: '1' requestBody: description: '' content: application/json: schema: $ref: >- #/components/schemas/Createanewcustomerwiththedataoftheothercustomerrequest required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: >- #/components/schemas/Createanewcustomerwiththedataoftheothercustomerresponse - example: status: success example: status: success '400': description: '' headers: {} content: application/json: schema: allOf: - $ref: >- #/components/schemas/Createanewcustomerwiththedataoftheothercustomerresponse1 - example: code: invalid_request error: Error message example: code: invalid_request error: Error message '409': description: One of the customers has a merge or unmerge operation in progress. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: >- Merge/unmerge operation in progress for one of the customers. example: code: datatransfer_running error: >- one of the customers in the request has a merge or unmerge running try again later example: code: datatransfer_running error: >- one of the customers in the request has a merge or unmerge running try again later deprecated: false /carts/realtime: post: tags: - carts - create a cart summary: Create a new cart in real time description: >-
The endpoint /activities/realtime is also available as a LEGACY version of this API.
An "Activity" in Loyal Guru primarily represents a purchase event, often referred to as a "cart" or "ticket." This method focuses on the real-time creation of such cart events. **Purpose of this method (Real-time Cart Creation):** This method allows you to create a new cart in real-time. It's designed for immediate processing and to provide insights upon creation. **Key Uses & Benefits:** - **Points & Discount Distribution Recommendation:** Automatically and optimally distribute points and discounts across individual cart lines, impacting both line totals and the overall cart total. This is especially helpful if manual calculation is undesirable. **Crucially, you can also use the results obtained from the simulation endpoint, eliminating the need to recalculate everything.** - **Error Detection:** Identify potential issues such as cashback calculation errors, return conflicts, or data integrity validation failures. **Promotions and Discounts (`coupons_desired` property):** By default, all massive and loyalty member promotions (points and discounts) without coupon are included and applied when calculating the ticket. You can control how vouchers are applied using the `coupons_desired` property: - `all`: Apply all masive + loyalty member promotions + all vouchers assigned to the customer. - `selected`: Apply all massive + loyalty member promotions + only vouchers previously selected by the customer via the appropriate endpoint. - `["34433", "465443"]`: apply all massive + loyalty member promotions without coupon + the vouchers/static code specified. - `[]` (empty array) or omit property: Apply only all massive and loyalty member promotions without coupon (no specific vouchers).. **Data Integrity and Coherence (Important Caveats):** - **Cart Integrity Validation:** This endpoint **does NOT** validate the integrity of the cart data (e.g., unique cart ID, unique order in each line). If you send a non-unique cart (same cart ID, same order in every line), the endpoint will respond as if successful, but **behind the scenes, the customer will NOT get points, NOT redeem vouchers, etc.** - **Cart Data Coherence:** This endpoint **does NOT** validate if the cart data is coherent (e.g., `cart.total` equals sum of `line.total`s, `customer_id` exists). If you send incoherent data, the endpoint will process everything anyway, and the customer **WILL** get their points. **Important Method Logic & Considerations:** - **Calculation Order:** The application order for calculations is: discounts burned first, then points burned (cashback), and finally points earned. - The `total` amount returned for cart lines is adjusted *after* applying all relevant discounts (promotional campaigns, vouchers, point-based discounts/cashback). - The original, unadjusted amount for each line item is preserved in the `original_total` attribute. - **Returns (`quantity` field):** Lines are only accepted for return if the `quantity` is less than or equal to the original cart line quantity. If different, the response will be an error. You are allowed to return the same original line across different activities. - **Cashback Distribution Limits:** The discount applied to a line (from cashback) must not exceed the defined maximum limit of the line's `original_total` (50% by default). The final `total` for a line must be divisible by its `quantity` with no more than two decimal places. Similarly, the points allocated to a line must be divisible by its `quantity` without decimals. - **Mutually Exclusive Fields:** `customer_id` and `customer_code` are mutually exclusive; use only one. - **Fraudulent Customers:** If a customer is flagged as potentially fraudulent, points will not be used for ticket discounts, even if available. However, the customer will still earn points for the purchase. **Cart Structure Summary:** - A **cart** has a `total` field representing the exact amount paid by the customer for the entire cart, including taxes and applied discounts. - Each **line** has a `total` field representing the exact amount paid for that specific line, including taxes and applied discounts. - The `total` field in a cart and a line should be **negative** if the cart is a **cart cancellation**. The same applies to the `quantity` field within a line. - **Multicurrency Note:** If a cart originates in a country with a different currency than the customer's registered country, the `international: true` field will be included in all cart responses. If both currencies are the same, this field will not be shown. **Tier 1 (Critical)** — See rate limit table operationId: CreateANewActivityInRealtime parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/Createanewactivityinrealtimerequest' required: true responses: '200': description: >- The response mirrors the request structure but includes new attributes that summarize applied discounts, earned points, used vouchers, and updated customer information. Additionally, the response may contain the following elements: + **`effects`**: Details all promotional campaigns (both points and discounts) that were applied to the cart. + **`scores`**: Provides a summary of loyalty points earned per line item. + **`vouchers`**: Lists targeted vouchers that were successfully applied to the cart. + **`cashbacks`**: Indicates the amount of discount (cash or loyalty scores) obtained per line item in the cart. Note: Cashback will not be available if the customer is flagged as fraudulent. + **`cashbacks_returns`**: Represents the loyalty scores returned to the customer following the return of an item that was originally purchased using score cashback. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Createanewactivityinrealtimeresponse' '400': description: '**Errors regarding simulate cart**' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: |- **Posible errors:** invalid_rewards: not enough points example: code: '"invalid_request"' error: '"cart with ID 1234 already exists"' example: code: '"invalid_request"' error: '"cart with ID 1234 already exists"' '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /carts/simulate: post: tags: - carts - simulate a cart summary: Simulate the creation of a new cart in real time description: >-
The endpoint /activities/simulate is also available as a LEGACY version of this API.
An "Activity" in Loyal Guru represents a cart event. **Purpose of this method (Pre-calculation/Simulation):** This method lets you simulate a new cart (like a purchase) in real-time. It's crucial for Loyalty Points and discount programs and should *always* be used before finalizing the ticket creation with the `POST /activities/realtime` method. **Key Uses:** - **Points & Discount Distribution Recommendation:** Get system recommendations on how to best distribute points and discounts across individual lines, affecting both line totals and the overall cart. This is especially helpful if you don't want to calculate it manually. - **Customer Status Preview:** Understand how a simulated purchase would update the customer's points and discount balance. - **Error Detection:** Identify potential issues such as cashback calculation errors, return conflicts, or data integrity validation failures. **Points and Discounts (`coupons_desired` property):** By default, all massive and loyalty member promotions (points and discounts) without coupon are included and applied when calculating the ticket. You can control how vouchers are applied using the `coupons_desired` property: - `all`: Apply all masive + loyalty member promotions + all vouchers assigned to the customer. - `selected`: Apply all massive + loyalty member promotions + only vouchers previously selected by the customer via the appropriate endpoint. - `["34433", "465443"]`: apply all massive + loyalty member promotions without coupon + the vouchers/static code specified. - `[]` (empty array) or omit property: Apply only all massive and loyalty member promotions without coupon (no specific vouchers). **Cashback Considerations (`cashback_score_desired`):** If you specify a `cashback_score_desired` value, you can bypass the manual cashback array calculation. Just provide the total points you wish to redeem. The response will then recommend a cashback array, prioritizing point distribution by `line_order` based on an internal algorithm. *Note: Specifying this parameter will change the total points and lines in the response compared to your initial request.* *Set to `-1` to force maximum points usage.* The discount applied to a line (from cashback) must not exceed the defined maximum limit of the line's `original_total`(50% by default). **Important Method Considerations:** - The application order for calculations is: **discounts burn first, then points burned, and finally points earned.** + The **`total`** amount of returned lines on the cart is adjusted after applying all relevant discounts, including those from promotional campaigns, vouchers, and any point-based discounts (cashback). + The original, unadjusted amount for each line item remains unchanged and is preserved in the **`original_total`** attribute. - `customer_id` and `customer_code` are mutually exclusive; use only one. - If a customer is flagged as potentially **fraudulent**, points won't be used for ticket discounts, even if available. However, the customer will still earn points for the purchase. - **Multicurrency Note:**. If a cart originates in a country with a different currency than the customer's registered country, the `international: true` field will be included in all cart responses. - **Points Rounding:** Points are always rounded *down*. For example: - If a campaign is `1€ = 10 points` and you purchase `2.99€`, you earn `29` points. - If a campaign is `1€ = 1 point` and you purchase `12.5€`, you earn `12` points. **Tier 1 (Critical)** — See rate limit table operationId: SimulateTheCreationOfANewActivityInRealtime parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: >- #/components/schemas/Simulatethecreationofanewactivityinrealtimerequest required: true responses: '200': description: >- The response mirrors the request structure but includes new attributes that summarize applied discounts, earned points, used vouchers, and updated customer information. Additionally, the response may contain the following elements: + **`effects`**: Details all promotional campaigns (both points and discounts) that were applied to the cart. + **`scores`**: Provides a summary of loyalty points earned per line item. + **`vouchers`**: Lists targeted vouchers that were successfully applied to the cart. + **`cashbacks`**: Indicates the amount of discount (cash or loyalty scores) obtained per line item in the cart. Note: Cashback will not be available if the customer is flagged as fraudulent. + **`cashbacks_returns`**: Represents the loyalty scores returned to the customer following the return of an item that was originally purchased using score cashback. headers: {} content: application/json: schema: allOf: - $ref: >- #/components/schemas/Simulatethecreationofanewactivityinrealtimeresponse '400': description: '**Errors regarding simulate cart**' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: |- **Possible errors:** invalid_rewards: not enough points example: code: '"invalid_request"' error: '"cart with id 1234 already exists"' example: code: '"invalid_request"' error: '"cart with id 1234 already exists"' '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /carts/{id}: get: tags: - carts summary: Get a Cart description: >-
The endpoint /activities/{id} is also available as a LEGACY version of this API.
An activity is the name in Loyal Guru equivalent to a purchase activity. **Multicurrency note:** if an activity is generated in a country with a currency that is different to the currency of the country that the customer is registered then *international = true* field will be shown in all the activity responses. In case that both currencies are the same this field will not be shown. **Tier 3 (Low)** — See rate limit table operationId: GetAnActivity parameters: - name: id in: path description: > Activity's id/code value. - If searching by id, then an integer must be provided, i.e. **1234** - If searching by code, then a string must be provided, i.e. **14SCODE-55** - If searching by code that contains special characters (such as `/` or `;`), they must be double-encoded: 1. First URL-encode the character (i.e. `/` becomes `%2F`) 2. Then URL-encode the result again (i.e. `%2F` becomes `%252F`) Example: For code `123/ABC;XYZ`, use `123%252FABC%253BXYZ` in the URL. required: true style: simple schema: type: integer example: 1234 - name: search_param in: query description: >- Field used to fetch the activity. Valid values are `id` and `code`. Values are mutually exclusive. Default: `id` style: form explode: true schema: type: string example: id responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/Getanactivityresponse' '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getanactivityresponse1' - description: Server error, try again and contact with support. example: error: Internal server error example: error: Internal server error deprecated: false /carts: get: tags: - carts summary: Get a list of Carts description: >-
The endpoint /activities is also available as a LEGACY version of this API.
An activity is the name in Loyal Guru equivalent to a purchase activity. **Multicurrency note:** if an activity is generated in a country with a currency that is different to the currency of the country that the customer is registered then *international = true* field will be shown in all the activity responses. In case that both currencies are the same this field will not be shown.Regarding filters: - `id`, `code` can´t be sent at the same time. - `customer_id`, `customer_code` and `location_id` can´t be sent at the same time. Just one of them is allowed. - `country` and `countries` are mutually exclusive and cannot be passed together in the same request. **Tier 3 (Low)** — See rate limit table operationId: GetAListOfActivities parameters: - name: customer_id in: query description: Will return all activities by customer. style: form explode: true schema: type: integer format: int64 example: 99302 - name: customer_code in: query description: Will return all activities by customer code. style: form explode: true schema: type: string example: 99302a - name: associate_id in: query description: >- Will return all activities by associate. **Mutually exclusive with customer_id and customer_code**. style: form explode: true schema: type: integer format: int64 example: 99301 - name: location_id in: query description: >- Activities in a given location. **Mutually exclusive with `location_code`**. style: form explode: true schema: type: integer format: int64 example: 21 - name: location_code in: query description: >- Activities in a given location. **Mutually exclusive with `location_id`**. style: form explode: true schema: type: string example: 789B - name: order_id in: query description: Activities by order. style: form explode: true schema: type: string example: order 101 - name: from_date in: query description: Activities filter in a given date range, equivalent to session. style: form explode: true schema: type: string example: '2017-12-31' - name: to_date in: query description: Activities filter in a given date range, equivalent to session. style: form explode: true schema: type: string example: '2018-12-31' - name: id in: query description: >- Activity by id. Will return only 1 activity as id is unique. **Mutually exclusive with `code`**. style: form explode: true schema: type: integer format: int64 example: 101 - name: code in: query description: > Activity by code. Will return only 1 activity as code is unique. **Mutually exclusive with `id`**. If the code contains special characters (such as `/` or `;`), they must be double-encoded: 1. First URL-encode the character (i.e. `/` becomes `%2F`) 2. Then URL-encode the result again (i.e. `%2F` becomes `%252F`) Example: For code `123/ABC;XYZ`, use `123%252FABC%253BXYZ` in the URL. style: form explode: true schema: type: string example: T1234 - name: per_page in: query description: 'Max number of activities returned per response. - Default: 10' style: form explode: true schema: type: integer format: int64 example: 20 - name: starting_after in: query description: >- You will receive this token on every response ( on the variable **next_token_starts_after** ) in order to have the next batch of elements. style: form explode: true schema: type: string example: token - name: country in: query description: >- Will return all activities by country (single country filtering). [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). **Mutually exclusive with `countries`**. style: form explode: true schema: type: string example: ES - name: countries in: query description: >- Will return all activities by multiple countries (multi-country filtering). [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). **Mutually exclusive with `country`**. style: form explode: true schema: type: string example: ES,IT responses: '200': description: >- Look the example below to be aware of all information returned per activity. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getalistofactivitiesresponse' - description: >- Look the example below to be aware of all information returned per activity. example: data: - id: 1234 code: T1234 barcode: '0012349437' creation_date: '2017-10-16T12:45:55Z' customer_id: 99302 associate_id: 99303 location_id: 43 total: 15.75 international: true score: 100 score_used: -20 score_returned_from_customer: -20 score_returned_to_customer: 40 business_name: Streaming Corp total_net: 14 total_tax: 1.75 tpv_id: AT123 staff_name: John Doe staff_code: john-doe currency: EUR score_simulation: true cashback_score_desired: 10 cashback_score_desired_unused: 8 custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom8: custom 8 value promotions: - promotion_id: 11 product_id: 34 discount: 4.1 line_order: 5 discount_int: 4 customer: id: 99302 code: 99302a score: 10 score_available: 10 score_as_money: 12.34 score_available_as_money: 12.04 score_threshold_cashback: 1000 money_threshold_cashback: 10 score_to_reach_cashback: 100 money_to_spend_to_reach_cashback: 0.1 fraudulent: false payments: - amount: 20 type: cash change: 4.25 cashbacks: - line_order: 1 score: 100 discount: 8.5 scores: - line_order: 1 score: 100 loyalty_score_id: 2 available_from: '2016-01-01' cashback_returns: - line_order: 1 score: 10 returns: - line_order: 2 quantity: 5.3 ticket_id: 12 ticket_code: a1b2c3d4 from_line_order: 1 score: 10 lines: - order: 1 total: 15.75 total_net: 14 total_tax: 1.75 total_cost: 16 original_total: 16 price: 16 quantity: 3 product_code: PR00987L product_ean: GHT567A product_id: 987 product_name: Product 987 1L product_tax: 21 custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom9: custom 9 value attributes: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true shipment: status: some_status tracking_code: some_code delivery_address: some-address company: some-company tracking_url: some-url status_histories: - status: first_status created_at: '2017-12-25T23:45:55Z' - status: second_status created_at: '2017-12-28T23:45:55Z' rewards: - id: 319 discount: 3.2 line_order: 2 product_id: 12 attributes: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true next_token_starts_after: token example: data: - id: 1234 code: T1234 barcode: '0012349437' creation_date: '2017-10-16T12:45:55Z' customer_id: 99302 associate_id: 99303 location_id: 43 total: 15.75 international: true score: 100 score_used: -20 score_returned_from_customer: -20 score_returned_to_customer: 40 business_name: Streaming Corp total_net: 14 total_tax: 1.75 tpv_id: AT123 staff_name: John Doe staff_code: john-doe currency: EUR score_simulation: true cashback_score_desired: 10 cashback_score_desired_unused: 8 custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom8: custom 8 value promotions: - promotion_id: 11 product_id: 34 discount: 4.1 line_order: 5 discount_int: 4 customer: id: 99302 code: 99302a score: 10 score_available: 10 score_as_money: 12.34 score_available_as_money: 12.04 score_threshold_cashback: 1000 money_threshold_cashback: 10 score_to_reach_cashback: 100 money_to_spend_to_reach_cashback: 0.1 fraudulent: false payments: - amount: 20 type: cash change: 4.25 cashbacks: - line_order: 1 score: 100 discount: 8.5 scores: - line_order: 1 score: 100 loyalty_score_id: 2 available_from: '2016-01-01' cashback_returns: - line_order: 1 score: 10 returns: - line_order: 2 quantity: 5.3 ticket_id: 12 ticket_code: a1b2c3d4 from_line_order: 1 score: 10 lines: - order: 1 total: 15.75 total_net: 14 total_tax: 1.75 total_cost: 16 original_total: 16 price: 16 quantity: 3 product_code: PR00987L product_ean: GHT567A product_id: 987 product_name: Product 987 1L product_tax: 21 custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom9: custom 9 value attributes: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true shipment: status: some_status tracking_code: some_code delivery_address: some-address company: some-company tracking_url: some-url status_histories: - status: first_status created_at: '2017-12-25T23:45:55Z' - status: second_status created_at: '2017-12-28T23:45:55Z' rewards: - id: 319 discount: 3.2 line_order: 2 product_id: 12 attributes: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true next_token_starts_after: token '400': description: >- When any of the parameters is not valid or missing, including when both country and countries are passed together. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getalistofactivitiesresponse1' - description: >- When any of the parameters is not valid or missing, including when both country and countries are passed together. example: error: country and countries can not be passed at the same time example: error: country and countries can not be passed at the same time '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getalistofactivitiesresponse1' - description: Server error, try again and contact with support. example: error: Internal server error example: error: Internal server error deprecated: false /carts/cancellation: post: tags: - carts - cancel a cart summary: Cancel a cart (total) by creating a new cart with negative amounts description: >- This endpoint facilitates the complete reversal of a prior purchase identified by the cart id or cart code. **IMPORTANT!:** To cancel a cart correctly and generate a rollback for all vouchers as expected, you must wait at least 5 minutes after the original cart creation. This delay ensures that all asynchronous processes related to points accrual and voucher issuance are completed before initiating the cancellation. If you do not wait this time, there is a risk that some vouchers may not be rolled back correctly. **Purpose.** The primary function is to process a full return where the customer cancels the entire cart. This ensures that the system accurately tracks the reversal of inventory, points and redeemed promotions. **Mechanism & Result.** Upon successful execution, the system performs the following: - A new order/cart object is generated (often referred to as a "Return Cart"). - This new object is a mirror copy of the original cart, but with all product quantities and associated monetary values (including products, coupons, and vouchers) represented as negative amounts. - The original cart is not modified. - The system is then triggered to process the rollback of all earned/used points, vouchers affected and return of stock plus reset of Limits. **Considerations** - A ticket cannot be canceled more than once, either partially or completely. - An automatic rollback would be triggered for all coupons that were applied to the original ticket, regardless of whether their application was full or partial. - A full cancellation requires the rollback of EVERY coupon that impacted the original ticket, whether applied to individual lines or to the ticket total. - It also includes the reversal of all points/wallet earned and redeemed in the original purchase. **Tier 3 (Low)** — See rate limit table operationId: CancelACart requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CancelACartRequest' - example: cart_to_cancel_code: ORD12345 new_cart_code: RET12345 required: true responses: '200': description: >- Success, server completed the request as expected, so the return cart has been created. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CancelACartResponse' '400': description: When parameters are missing or invalid. headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: invalid_request error: >- cart_to_cancel_id is colliding with another mutually exclusive field - code: invalid_request error: >- cart_to_cancel_code is colliding with another mutually exclusive field - code: invalid_request error: >- new_cart_code is colliding with another mutually exclusive field - code: invalid_request error: >- new_cart_id is colliding with another mutually exclusive field - code: invalid_request error: >- associate_id is colliding with another mutually exclusive field - code: invalid_request error: new_cart_code already exists - code: invalid_request error: new_cart_id already exists - code: invalid_request error: cart_to_cancel_code does not exist - code: invalid_request error: cart_to_cancel_id does not exist '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code '404': description: Not found, the requested includes a resource that does not exist. headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: not_found error: cart_to_cancel_id not found - code: not_found error: cart_to_cancel_code not found '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code deprecated: false /custom_events: post: tags: - custom events - create a custom event summary: Create a new Custom Event description: >-
The endpoint /custom_entities is also available as a LEGACY version of this API.
Create a new custom entity **Tier 2 (Moderate)** — See rate limit table operationId: CreateCustomEntity parameters: [] requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/CustomEntityCreateRequest' example: id: fc12345 customer_id: 123456789 customer_code: code123456789 slug: fishing_course data: prey_count: 25 location: BCN created_at: '2023-01-01T12:00:00Z' required: true responses: '201': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomEntityResponse' - description: >- Look the example below to be aware of all information returned per custom entity example: id: fc12345 customer_id: 123456789 customer_code: code123456789 slug: fishing_course data: prey_count: 25 location: BCN created_at: '2023-01-01T12:00:00Z' ingested_at: '2023-11-11T12:00:00Z' score: 700 score_available: 200 scores: - score: 200 loyalty_score_id: 1 available_from: '2023-07-10' available_to: '2023-12-31' - score: 500 loyalty_score_id: 123 available_from: '2024-01-01' available_to: '2024-12-31' customer: code: code123456789 id: 123456789 score: 700 score_available: 200 '202': description: >- When a custom entity is already created due to a duplicated request and the response is still cached headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomEntityResponse' - description: >- Look the example below to be aware of all information returned per custom entity example: id: fc12345 customer_id: 123456789 customer_code: code123456789 slug: fishing_course data: prey_count: 25 location: BCN created_at: '2023-01-01T12:00:00Z' ingested_at: '2023-11-11T12:00:00Z' score: 700 score_available: 200 scores: - score: 200 loyalty_score_id: 1 available_from: '2023-07-10' available_to: '2023-12-31' - score: 500 loyalty_score_id: 123 available_from: '2024-01-01' available_to: '2024-12-31' customer: code: code123456789 id: 123456789 score: 700 score_available: 200 '400': description: When any of the request parameters is invalid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the request parameters is invalid or missing. example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false get: tags: - custom events security: - api_key: [] summary: Get a list of Custom Events description: >-
The endpoint /custom_entities is also available as a LEGACY version of this API.
Get the list of custom entities, being able to optionally filter by id, customer_id, customer_code, created_at or slug **Tier 3 (Low)** — See rate limit table operationId: GetAListOfCustomEntities parameters: - name: id in: query description: Id of the custom entity. style: form explode: true schema: type: string example: asdf12345 - name: customer_id in: query description: Id of the owner customer. style: form explode: true schema: type: integer format: int64 example: 123456789 - name: customer_code in: query description: Code of the owner customer. style: form explode: true schema: type: string example: code123456789 - name: slug in: query description: Code of the custom entity definition. style: form explode: true schema: type: string example: fishing_course - name: created_at_gt in: query description: >- If specified, it will return the custom entities created after this date. The format must be [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) style: form explode: true schema: type: string example: '2023-08-31' - name: starting_after in: query description: >- Yo will receive this token on every response ( on the variable **next_token_starts_after** ) in order to have the next batch of elements. style: form explode: true schema: type: string example: token responses: '200': description: A `list` containing all found custom entities. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomEntityListResponse' - description: A `list` array will contain all found custom entities. example: data: - id: fc12345 customer_id: 123456789 customer_code: code123456789 slug: fishing_course data: prey_count: 25 location: BCN created_at: '2023-01-01T12:00:00Z' ingested_at: '2023-11-11T12:00:00Z' next_token_starts_after: token '400': description: When the parameter is invalid. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the request parameters is invalid or missing. example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code deprecated: false /custom_events/{id}: get: tags: - custom events summary: Get a Custom Event description: >-
The endpoint /custom_entities/{id} is also available as a LEGACY version of this API.
Get a custom entity by its identifier **Tier 3 (Low)** — See rate limit table operationId: GetACustomEntity parameters: - name: id in: path description: Id of the custom entity. style: form explode: true schema: type: string example: asdf12345 responses: '200': description: The custom entity with the provided identifier. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomEntityResponse' - description: >- Look the example below to be aware of all information returned per custom entity example: id: fc12345 customer_id: 123456789 customer_code: code123456789 slug: fishing_course data: prey_count: 25 location: BCN created_at: '2023-01-01T12:00:00Z' ingested_at: '2023-11-11T12:00:00Z' '404': description: When the custom entity is not found. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the request parameters is invalid or missing. example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code deprecated: false /trigger: post: tags: - triggers - process a trigger for a specific customer summary: Process a trigger for a specific customer description: >-
The endpoint /scores/trigger is also available as a LEGACY version of this API.
This endpoint allows you to programmatically trigger a Points or Wallet campaign when a specific condition is fulfilled. Customers earn points based on predefined campaigns. These rules can be applied in different scenarios, such as purchases, user sign-ups, or custom events defined by your integration. Accumulated points can later be redeemed for discounts, rewards, or coupons. Points campaigns can be triggered either by specifying a loyalty rule ID or by using a trigger associated with one or more campaigns. **Important:** - Both the trigger and the loyalty rule(s) must exist in the system. - The campaign must be associated with the trigger. **Endpoint Versions**: There are two versions of this endpoint, depending on the loyalty engine in use. Version 1: - If multiple loyalty rules are associated with the same trigger, only one rule will be executed. - The rule selection order is not guaranteed. - It is strongly recommended to use the loyalty_rule_id to ensure the correct loyalty rule is triggered. Version 2: - If multiple loyalty rules are associated with the same trigger, all associated rules will be executed and all points will be granted if conditions are met. - To apply only one rule, you must explicitly specify the loyalty_rule_id. **Additional Considerations:** - The customer must be active to be eligible to earn points. - Some campaigns may limit the number of times a customer can earn points. **Tier 1 (Critical)** — See rate limit table operationId: Trigger parameters: [] requestBody: description: '' content: application/json: schema: oneOf: - $ref: '#/components/schemas/TriggerRequestCustomerID' - $ref: '#/components/schemas/TriggerRequestCustomerCode' examples: TriggerRequestCustomerID: value: trigger: manual customer_id: 10 loyalty_score_id: 12 score_overwrite: 30 comments: 30 extra points for completing the poll TriggerRequestCustomerCode: value: trigger: manual customer_code: 233311-b22e-449b-8564-932222 loyalty_score_id: 12 score_overwrite: 30 comments: 30 extra points for completing the poll required: true responses: '200': description: Success, server completed the request as expected headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/TriggerResponse' '400': description: >- Bad request, the request is invalid, such as lacking required request body or parameter **Possible errors and validations:** + Customer is inactive or does not exist. + Win limit for loyalty rule has been reached for the provided customer. + no trigger campaign found for the requested conditions or win limits exceeded + Location not found or does not exist in provided country. + Country not accepted headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/TriggerResponseError' example: - code: invalid_request error: customer is inactive - code: invalid_request error: the provided location is not in the provided country - code: invalid_request error: customer not found - code: customer_invalid error: customer id {id} doesn't have registration location - code: invalid_request error: win limit exceeded - code: invalid_request error: location not found - code: invalid_request error: >- country: country must be one of the following: AD, AE, AF, AG, AI, AL, AM, AN, AO, AR, AS, AT, AU, AW, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, ST, SV, SY, SZ, SX, TC, TD, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW '404': description: |- Not found, the requested resource does not exist. **Possible causes:** + Loyalty rule is disabled. + current date not between validity dates of provided loyalty rule. + Loyalty rule or trigger provided does not exist. + trigger provided does not match provided loyalty rule headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/TriggerResponseError' example: - code: trigger_not_found error: no loyalty rule found for trigger '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message deprecated: false /discounts: post: tags: - discounts summary: Create a New discount campaign description: >- This endpoint allows you to create a new **discount campaign**. This process involves creating a Loyalty Campaign and, if the campaign is configured for targeted customers, an associated Coupon (by providing `coupon_params`). **Tier 3 (Low)** — See rate limit table operationId: CreateANewDiscountCampaign requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateNewDiscountsCampaignRequest' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessWithId' - example: status: success id: 223222 example: status: success id: 223222 '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code get: tags: - discounts security: - api_key: [] summary: Get available discount campaigns description: >- Returns a list of discount campaigns available under different conditions (see query parameters for filtering options). **Use cases:** - Build a **Customer Discount Campaigns Catalogue**: when filtered by customer, the endpoint returns all discount campaigns available to that customer, considering their country and the specific targeted campaigns they belong to. - Get all discount campaigns available in a given country or store. **Note:** Campaigns response order: 1. Massive Campaigns 2. Loyalty Member Campaigns 3. Targeted Campaigns **Considerations:** 1. Returns Only campaigns available today considering available_from and available_to dates. 2. Returns Only campaigns that are active considering active flag. 3. For targeted campaigns, it does not return cancelled vouchers and vouchers with no more redemptions available 4. If the same campaign was sent more than once to a specific customer, it will return all of them and you can use campaign_history_id to get the specific delivery. Refer to the JSON response schema below for details. **Tier 3 (Low)** — See rate limit table operationId: GetAListOfDiscountCampaigns parameters: - name: campaign_audience in: query description: >- Type of discount campaign. If not provided, it will return all types of discount campaigns (massive, loyalty member campaigns and targeted). Possible values: - `all_customers`: returns only massive discount campaigns available. - `loyalty`: returns only loyalty member discount campaigns available. - `targeted`: returns only targeted discount campaigns available. All these types of campaigns can be filtered by country, location or customer (see other parameters). style: form schema: type: string example: loyalty - name: location_id in: query description: >- 'Filter discount campaigns available in certain location. If both `location_id` and `location_code` are provided, only `location_id` will be considered. Mutually exclusive with `countries`.' style: form explode: true schema: type: integer format: int64 example: 1234 - name: location_code in: query description: >- Filter discount campaigns available in certain location, considering massive campaigns and loyalty member campaigns. If both `location_id` and `location_code` are provided, only `location_id` will be considered. Mutually exclusive with `countries`.' style: form explode: true schema: type: string example: abc - name: customer_id in: query description: >- ID of the customer. Mutually exclusive with `customer_code`. Filter discount campaigns defined for the country of the customer and specific targeted campaigns for that customer. If this value (or customer code) is sent as a parameter, it will return all the discount campaigns available in the customer's country of registration (massive campaigns and loyalty member campaigns) plus the specific targeted campaigns for that customer. style: form explode: true schema: type: integer format: int64 example: 12345 - name: customer_code in: query description: >- Code of the customer. Mutually exclusive with `customer_id`. Filter discount campaigns defined for the country of the customer and specific targeted campaigns for that customer. If this value (or customer id) is sent as a parameter, it will return all the discount campaigns available in the customer's country of registration (massive campaigns and loyalty member campaigns) plus the specific targeted campaigns for that customer. style: form explode: true schema: type: string example: 12345a - name: countries in: query description: >- Countries where the discount campaign is available. Mutually exclusive with `location_id` or `location_code`. For more than one country, example: countries=ES&countries=FR . It will return discount campaigns for Spain **OR** France (massive campaigns and loyalty member campaigns style: form explode: true schema: type: string items: type: string example: ES - name: tier_id in: query description: >- Returns all active discount campaigns applicable to the loyalty tier level (massive campaigns and loyalty member campaigns) Mutually exclusive with `customer_id` or `customer_code`. style: form explode: true schema: type: integer format: int64 example: 12345 - name: category_id in: query description: >- Returns all active discount campaigns applicable to the specified category. style: form explode: true schema: type: integer format: int64 example: 2 - name: selected in: query description: >- If true returns only the discount campaigns vouchers that are currently selected for the customer (only applicable when `customer_id` or `customer_code` is provided and `location_id` or `location_code` is provided). If false, it returns only discount campaigns vouchers for that customer that are not selected (considering targeted campaigns only). If not provided, it returns all discount campaigns vouchers for that customer, regardless of their selection status. If you want to get only targeted campaigns you have to use the campaign_audience parameter with the value 'targeted'. Otherwise it will include massive and loyalty campaigns in the style: form explode: true schema: type: boolean example: true - name: starting_after in: query description: >- You will receive this number on every response (on the variable **next_token_starts_after**) in order to have the next batch of elements. style: form explode: true schema: type: string example: '100' responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetAListOfDiscountCampaignResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: code: invalid_request error: error message example: code: invalid_request error: error message '404': description: When is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /discounts/{value}: patch: tags: - discounts summary: Update a discount campaign description: |- Updates a discount campaign. **Tier 3 (Low)** — See rate limit table operationId: UpdateADiscountCampaign parameters: - name: value in: path description: Id of the campaign to be updated required: true style: simple schema: type: integer format: int64 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateADiscountCampaignRequest' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false get: tags: - discounts summary: Get a Discount campaign by id description: '**Tier 3 (Low)** — See rate limit table' operationId: GetADiscountCampaignByID parameters: - name: value in: path description: >- The value which you want to search by. This value can be related to the campaign id, the voucher code, the voucher id, the static code of the coupon or the campaign history id. required: true style: simple schema: type: integer format: int64 example: 1234 - name: search_by in: query description: |- The field by which the search will be performed. * If you want to search by campaign id, you can skip this parameter or set it to `loyalty_rule_id`. * If you want to search by campaign history id (a specific delivery of the campaign) you need to set this parameter to `campaign_history_id`. * if you want to search by voucher_code you need to set this parameter to `voucher_code`. * if you want to search by voucher_id, you can skip this parameter or set it to `voucher_id`. * if you want to search by static code of the coupon, you can skip this parameter or set it to `static_code`. * If this parameter is not sent, the search will be performed by campaign id. explode: true schema: type: string example: campaign_history_id responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/DiscountResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the campaign is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the campaign is not found example: code: invalid_request error: error message example: code: invalid_request error: error message '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /discounts/redeem: post: tags: - discounts summary: Redeem discount description: |- This endpoint allows clients to redeem a specific voucher or coupon. It is designed to handle both types of coupons: - Coupons that generate vouchers: used in targeted campaigns. - Coupons that do not generate vouchers: used in massive or loyalty campaigns **Tier 2 (Moderate)** — See rate limit table operationId: RedeemADiscount requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/RedeemADiscountRequest' required: true responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/RedeemADiscountResponse' example: rule_id: 555253114 campaign_history_id: 7206 rule_name: Rule name type: discount effect_type: external_redeem distribution_type: total value: 1500 value_as_money: 1500 select_customers: targeted coupon_info: voucher_id: 31176968 voucher_code: '212128711' coupon_id: 100004180 coupon_name: Coupon name static_code: AAHY79212 '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /discounts/transactions: get: tags: - discounts summary: >- Show a customer's history of redeemed discounts from promotional campaigns. description: >- Retrieves all discounts applied by promotional campaigns, grouped by event type. A record is generated for each event associated with a discount campaign (e.g., cart event). **Tier 3 (Low)** — See rate limit table operationId: GetListDiscountsTransactions parameters: - name: customer_id in: query description: >- Mutually exclusive with `customer_code`. Specify the customer for which you'd like to retrieve the discount history. style: form explode: true schema: type: integer example: 787665252 - name: customer_code in: query description: >- Mutually exclusive with `customer_id`. Specify the customer for which you'd like to retrieve the discount history. style: form explode: true schema: type: string example: a1b2c3d4-4jfhdksl2 - name: starting_after in: query description: Pagination token in order to have the next batch of elements. style: form explode: true schema: type: string example: 11 responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetListDiscountsTransactionsResponse' example: data: - id: 123119 created_at: '2017-12-12T13:45:22Z' amount: 899.12 customer_id: 2323 activity_id: 4327463374 - id: 123119 created_at: '2019-12-12T13:45:22Z' amount: 1 customer_id: 2323 activity_id: 12223332 next_token_starts_after: '234' '400': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: '' example: code: bad_request error: error message '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /discounts/trigger: post: tags: - discounts operationId: TriggerACouponWithADiscountForACustomer summary: Trigger a coupon with a discount for a customer description: >- This endpoint allows you to trigger a coupon with a discount for a customer. **Important Notes:** - This endpoint only works for coupons or for discount campaigns of the type **Targeted** - You must provide either `customer_id` or `customer_code` (mutually exclusive) - You must provide either `coupon_id` or `loyalty_rule_id` (mutually exclusive, but at least one is required) - `external_voucher_code` is optional and has no validation - any value provided will be used as-is for voucher code generation - `priority_allocation` is optional - when set to `true`, the voucher will be generated and assigned with maximum priority - **Rate Limit:** This endpoint has a limit of **50 Request Per Second (RPS)** **Tier 1 (Critical)** — See rate limit table security: - api_key: [] parameters: [] requestBody: description: '' content: application/json: schema: oneOf: - $ref: >- #/components/schemas/DiscountTriggerRequestCustomerIDCouponID - $ref: >- #/components/schemas/DiscountTriggerRequestCustomerCodeCouponID - $ref: >- #/components/schemas/DiscountTriggerRequestCustomerIDLoyaltyRuleID - $ref: >- #/components/schemas/DiscountTriggerRequestCustomerCodeLoyaltyRuleID examples: Customer ID with Coupon ID: value: customer_id: 1 coupon_id: 2 Customer ID with Coupon ID (with optional fields): value: customer_id: 1 coupon_id: 2 external_voucher_code: EXT123 priority_allocation: true Customer Code with Coupon ID: value: customer_code: 12345a coupon_id: 2 Customer Code with Coupon ID (with optional fields): value: customer_code: 12345a coupon_id: 2 external_voucher_code: EXT123 priority_allocation: true Customer ID with Loyalty Rule ID: value: customer_id: 1 loyalty_rule_id: 5 Customer ID with Loyalty Rule ID (with optional fields): value: customer_id: 1 loyalty_rule_id: 5 external_voucher_code: EXT123 priority_allocation: true Customer Code with Loyalty Rule ID: value: customer_code: 12345a loyalty_rule_id: 5 Customer Code with Loyalty Rule ID (with optional fields): value: customer_code: 12345a loyalty_rule_id: 5 external_voucher_code: EXT123 priority_allocation: true required: true responses: '200': description: Success, server completed the request as expected headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' example: status: success '400': description: >- When any of the parameters is not valid or missing. Possible error messages: - "either coupon_id or loyalty_rule_id must be provided" - "loyalty rule has no associated coupon" - "loyalty rule is not targeted" - "coupon not found for this coupon: {id}" - "coupon is inactive" - "coupon is not available" - "coupon does not have an affectation" - "customer not found" - "customer is inactive" - "loyalty rule has invalid dates for the associated coupon" - Other validation errors from coupon or loyalty rule validation headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' examples: MissingCouponOrLoyaltyRule: value: code: invalid_request error: either coupon_id or loyalty_rule_id must be provided CustomerNotFound: value: code: invalid_request error: customer not found CustomerInactive: value: code: invalid_request error: customer is inactive LoyaltyRuleNoCoupon: value: code: invalid_request error: loyalty rule has no associated coupon LoyaltyRuleNotTargeted: value: code: invalid_request error: loyalty rule is not targeted CouponInactive: value: code: invalid_request error: coupon is inactive '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' '404': description: When the loyalty rule is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' example: code: not_found error: loyalty rule not found '429': description: >- Too Many Requests. Returned when the rate limit of 50 Request Per Second (RPS) is exceeded. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' example: code: too_many_requests error: rate limit exceeded '500': description: >- Server error, try again and contact with support. This can occur when: - There is an error enqueueing the job (e.g., "internal_error") - Other unexpected server errors headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' example: code: internal_error error: error message /games: get: tags: - Games security: - api_key: [] summary: Get available game campaigns description: >- Returns a list of game campaigns available under different conditions (see query parameters for filtering options). **Use cases:** - Build a **Customer Game Campaigns Catalogue**: when filtered by customer, the endpoint returns all game campaigns available to that customer, considering their country and the specific targeted campaigns they belong to. - Get all game campaigns available in a given country or store. **Note:** Campaigns response order: 1. Loyalty Member Campaigns 2. Targeted Campaigns For targeted campaigns, each item may include `loyalty_rule_history_id`. Use that value with `GET /games/{id}?search_by=loyalty_rule_history_id` to retrieve the historical snapshot for that specific delivery. Multi-language content (e.g. name, description) follows the **Accept-Language** header. Refer to the JSON response schema below for details. **Tier 3 (Low)** — See rate limit table operationId: GetAListOfGameCampaigns parameters: - name: campaign_audience in: query description: >- Type of game campaign. If not provided, it will return all types (loyalty member campaigns and targeted). Possible values: - `loyalty`: returns only loyalty member game campaigns available. - `targeted`: returns only targeted game campaigns available. All these types can be filtered by country, location or customer (see other parameters). style: form schema: type: string example: loyalty - name: location_id in: query description: >- Filter game campaigns available in a certain location (loyalty member campaigns). If both `location_id` and `location_code` are provided, only `location_id` will be considered. Mutually exclusive with `countries`. style: form explode: true schema: type: integer format: int64 example: 1234 - name: location_code in: query description: >- Filter game campaigns available in a certain location (loyalty member campaigns). If both `location_id` and `location_code` are provided, only `location_id` will be considered. Mutually exclusive with `countries`. style: form explode: true schema: type: string example: abc - name: customer_id in: query description: >- ID of the customer. Mutually exclusive with `customer_code`. Filter game campaigns defined for the country of the customer and specific targeted campaigns for that customer. If sent, returns all game campaigns available in the customer's country (loyalty member campaigns) plus targeted campaigns for that customer. style: form explode: true schema: type: string example: '12345' - name: customer_code in: query description: >- Code of the customer. Mutually exclusive with `customer_id`. Filter game campaigns defined for the country of the customer and specific targeted campaigns for that customer. style: form explode: true schema: type: string example: 12345a - name: countries in: query description: >- Countries where the game campaign is available. Mutually exclusive with `location_id` or `location_code`. For more than one country, use countries=ES&countries=FR to return game campaigns for Spain **OR** France. style: form explode: true schema: type: string items: type: string example: ES - name: tier_id in: query description: >- Returns all active game campaigns applicable to the loyalty tier level. Mutually exclusive with `customer_id` or `customer_code`. style: form explode: true schema: type: integer format: int64 example: 12345 - name: starting_after in: query description: >- Cursor for pagination. Use the value of **next_token_starts_after** from the previous response to get the next page. style: form explode: true schema: type: string example: '100' - name: per_page in: query description: Number of items per page (pagination). style: form explode: true schema: type: integer format: uint example: 20 responses: '200': description: List of game campaigns headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetAListOfGameCampaignResponse' '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: code: invalid_request error: error message example: code: invalid_request error: error message '404': description: When not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' example: error: error message code: error code '500': description: Server error, try again and contact support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' example: code: server_error error: error message deprecated: false /games/{id}: get: tags: - Games security: - api_key: [] summary: Get a game campaign by ID description: >- Returns a single game campaign. Use `search_by` to choose how the path `id` is interpreted. If `search_by=loyalty_rule_history_id`, then path `id` must be a `loyalty_rule_history_id` value. For targeted game historical snapshots, use `search_by=loyalty_rule_history_id`. This lookup is only valid for targeted gaming campaigns; otherwise, the API returns `400 invalid_request`. Multi-language content (e.g. name, description) follows the **Accept-Language** header. **Tier 3 (Low)** — See rate limit table operationId: GetAGameCampaignById parameters: - name: id in: path description: |- Identifier value according to `search_by`. Examples: - `search_by=loyalty_rule_id` -> game campaign ID - `search_by=loyalty_rule_history_id` -> loyalty rule history ID (targeted gaming snapshot) required: true style: simple schema: type: integer format: int64 example: 3001 - name: search_by in: query required: false description: >- Lookup strategy for path `id`. For historical targeted game detail, use `loyalty_rule_history_id`. schema: type: string enum: - loyalty_rule_id - loyalty_rule_history_id - campaign_history_id - static_code default: loyalty_rule_id example: loyalty_rule_history_id responses: '200': description: The game campaign headers: {} content: application/json: schema: $ref: '#/components/schemas/GameCampaignResponse' example: id: 3001 name: Lucky Wheel description: >- Spin the wheel once per day and win discounts or points on your next purchase. active: true available_from: '2025-01-01' available_to: '2025-12-31' recurrence_type: daily recurrence_days: [] select_customers: loyalty customer_registration_countries: - ES - PT loyalty_rule_category: id: 10 name: Seasonal promotions priority: 1 category_type: seasonal rule_conditions: '{"min_points": 0, "allowed_tiers": [1, 2, 3]}' rule_application: '{"max_plays_per_period": 1, "period": "day"}' rule_effects: '{"apply_best_prize": true}' rule_type: gaming game: id: 1 loyalty_rule_id: 3001 type: wheel config: '{"spins": 1, "theme": "default", "sectors": 8}' template: default game_prizes: - id: 1 game_id: 1 name: 10% off your next purchase outcome: discount display_options: '{"icon": "percent", "color": "#2E7D32"}' weight: 0.15 stock: 500 stock_management_strategy: decrement - id: 2 game_id: 1 name: 50 bonus points outcome: points display_options: '{"icon": "star", "color": "#FFC107"}' weight: 0.25 stock: 1000 stock_management_strategy: decrement - id: 3 game_id: 1 name: Try again outcome: no_prize display_options: '{"icon": "refresh"}' weight: 0.6 stock: -1 stock_management_strategy: unlimited priority: 5 stackability_properties: null when: null once: null once_limit: null '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' example: code: invalid_request error: >- search_by=loyalty_rule_history_id is only supported for targeted gaming campaigns '404': description: Game campaign not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' example: error: error message code: game_not_found '500': description: Server error, try again and contact support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' example: code: server_error error: error message deprecated: false /games/{id}/play: post: tags: - Games security: - api_key: [] summary: Play a game description: >- Executes a play for the given game campaign. The customer is identified by either `customer_id` or `customer_code` in the request body. The game engine evaluates eligibility (campaign dates, audience, location, etc.), selects a prize according to the game configuration, and applies the corresponding effect (e.g. discount, points, voucher). The response returns the list of **effects** applied for this play. For targeted audience game campaigns, you must send `loyalty_rule_history_id` in the request body with the history assigned to the customer. If the history is missing or does not match the targeted campaign, the response is still `200` with an empty `effects` array. For non-targeted campaigns, `loyalty_rule_history_id` is optional and does not change the expected play behavior. If the customer and game do not match (for example, the customer is not eligible to play), the response is still 200 with an empty `effects` array. If the customer can play but no prize is selected, the response is still 200 and the effect status is `no_prize`. If a prize is selected but stock is already exhausted, the response is still 200 and the effect status is `stock_exhausted`. **Tier 3 (Low)** — See rate limit table operationId: PlayAGame parameters: - name: id in: path description: ID of the game campaign to play required: true style: simple schema: type: integer format: int64 example: 3001 requestBody: description: >- Customer identifier; exactly one of customer_id or customer_code is required. For targeted audience campaigns, include `loyalty_rule_history_id`. content: application/json: schema: $ref: '#/components/schemas/GamePlayRequest' examples: by_customer_id: summary: Play by customer ID value: customer_id: 8223342 by_customer_code: summary: Play by customer code value: customer_code: 8223a targeted_campaign: summary: Play for targeted campaign value: customer_id: 8223342 loyalty_rule_history_id: 900004 required: true responses: '200': description: >- Play completed. Effects contain the selected game outcome, including no-prize and stock-exhausted outcomes. If the customer cannot play this game, `effects` is empty. headers: {} content: application/json: schema: $ref: '#/components/schemas/GamePlayResponse' examples: points_prize: summary: Points prize won value: code: success effects: - game_info: config: '{"defeat_message": "lose", "victory_message": "win"}' game_id: 101 game_type: scratch outcome: >- {"promotion_id": 1234568150, "promotion_type": "points"} prize_id: 125 status: won status_message: Prize won and applied successfully template: String: '' Valid: false won_prize: name: Test points prize points: 100 type: points line: 0 order_apply: 0 rule_id: 1234568641 rule_name: test play rule_unique_id: '1234568641' select_customers: loyalty type: gaming discount_prize: summary: Discount prize won value: code: success effects: - game_info: config: '{"defeat_message": "lose", "victory_message": "win"}' game_id: 101 game_type: scratch outcome: >- {"promotion_id": 1234568607, "promotion_type": "discount"} prize_id: 127 status: won status_message: Prize won and applied successfully template: String: '' Valid: false won_prize: available_from: '2026-03-04' available_to: '2026-03-22' image_url: '' name: Test manu type: discount line: 0 order_apply: 0 rule_id: 1234568641 rule_name: test play rule_unique_id: '1234568641' select_customers: loyalty type: gaming coupon_prize: summary: Coupon prize won value: code: success effects: - game_info: config: '{"defeat_message": "lose", "victory_message": "win"}' game_id: 101 game_type: scratch outcome: >- {"promotion_id": 1234568999, "promotion_type": "coupon"} prize_id: 129 status: won status_message: Prize won and applied successfully template: String: '' Valid: false won_prize: available_from: '2026-03-04' available_to: '2026-03-22' image_url: '' name: Test coupon description: Coupon description type: coupon line: 0 order_apply: 0 rule_id: 1234568641 rule_name: test play rule_unique_id: '1234568641' select_customers: loyalty type: gaming no_prize: summary: No prize won value: code: success effects: - game_info: config: '{"defeat_message": "lose", "victory_message": "win"}' game_id: 101 game_type: scratch outcome: '{}' prize_id: 128 status: no_prize status_message: No prize won (outcome empty) template: String: '' Valid: false line: 0 order_apply: 0 rule_id: 1234568641 rule_name: test play rule_unique_id: '1234568641' select_customers: loyalty type: gaming stock_exhausted: summary: Prize selected but stock exhausted value: code: success effects: - game_info: config: '{"defeat_message": "lose", "victory_message": "win"}' game_id: 101 game_type: scratch outcome: >- {"promotion_id": 1234568150, "promotion_type": "points"} prize_id: 125 status: stock_exhausted status_message: Prize won but stock was already exhausted template: String: '' Valid: false line: 0 order_apply: 0 rule_id: 1234568641 rule_name: test play rule_unique_id: '1234568641' select_customers: loyalty type: gaming customer_not_eligible: summary: Customer cannot play this game value: code: success effects: [] '400': description: >- Invalid request (e.g. invalid game id, invalid or missing customer identifier, customer not found). headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_game_id: summary: Invalid game id value: code: invalid_request in get game id error: invalid game id parameter invalid_json: summary: Invalid JSON body value: code: invalid_request in bind json error: (validation message) missing_customer: summary: Missing customer identifier value: code: invalid_request in validate request error: either customer_id or customer_code must be provided dependencies: summary: Error resolving customer or company value: code: invalid_request in get dependencies error: (error detail) '500': description: Server error while claiming or applying the prize. headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_server_error error: (error detail) deprecated: false /points: post: tags: - points & wallet summary: Create a New points campaign description: |- This endpoint is used to **create a new promotional points campaign**. Please consult with the support team for the correct application of the request payload to ensure campaigns function properly. **Tier 3 (Low)** — See rate limit table operationId: CreateANewPointsCampaign requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateNewPointsCampaignRequest' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessWithId' - example: status: success id: 3343333 example: status: success id: 3343333 '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code get: tags: - points & wallet security: - api_key: [] summary: Get available points/wallet campaigns description: >- Returns a list of points campaigns available under different conditions (see query parameters for filtering options). **Use cases:** - Build a **Customer Points Campaigns Catalogue**: when filtered by customer, the endpoint returns all points campaigns available to that customer, considering their country and the specific targeted campaigns they belong to. - Get all points campaigns available in a given country or store. **Note:** Campaigns response order: 1. Loyalty Member Campaigns 2. Targeted Campaigns Refer to the JSON response schema below for details. **Tier 3 (Low)** — See rate limit table operationId: GetAListOfScoreCampaigns parameters: - name: campaign_audience in: query description: >- Type of points campaign. If not provided, it will return all types of points campaigns (loyalty member campaigns and targeted). Possible values: - `loyalty`: returns only loyalty member points campaigns available. - `targeted`: returns only targeted points campaigns available. All these types of campaigns can be filtered by country, location or customer (see other parameters). style: form schema: type: string example: loyalty - name: location_id in: query description: >- 'Filter points campaigns available in certain location (loyalty member campaigns). If both `location_id` and `location_code` are provided, only `location_id` will be considered. Mutually exclusive with `countries`.' style: form explode: true schema: type: integer format: int64 example: 1234 - name: location_code in: query description: >- Filter points campaigns available in certain location, considering loyalty member campaigns. If both `location_id` and `location_code` are provided, only `location_id` will be considered. Mutually exclusive with `countries`.' style: form explode: true schema: type: string example: abc - name: customer_id in: query description: >- ID of the customer. Mutually exclusive with `customer_code`. Filter points campaigns defined for the country of the customer and specific targeted campaigns for that customer. If this value (or customer code) is sent as a parameter, it will return all the points campaigns available in the customer's country of registration (loyalty member campaigns) plus the specific targeted campaigns for that customer. style: form explode: true schema: type: integer format: int64 example: 12345 - name: customer_code in: query description: >- Code of the customer. Mutually exclusive with `customer_id`. Filter points campaigns defined for the country of the customer and specific targeted campaigns for that customer. If this value (or customer id) is sent as a parameter, it will return all the points campaigns available in the customer's country of registration (loyalty member campaigns) plus the specific targeted campaigns for that customer. style: form explode: true schema: type: string example: 12345a - name: countries in: query description: >- Countries where the points campaign is available. Mutually exclusive with `location_id` or `location_code`. For more than one country, example: countries=ES&countries=FR . It will return points campaigns for Spain **OR** France style: form explode: true schema: type: string items: type: string example: ES - name: tier_id in: query description: >- Returns all active points campaigns applicable to the loyalty tier level. Mutually exclusive with `customer_id` or `customer_code`. style: form explode: true schema: type: integer format: int64 example: 12345 - name: selected in: query description: >- If true returns only the points campaigns vouchers that are currently selected for the customer (only applicable when `customer_id` or `customer_code` is provided). If false, it returns only points campaigns vouchers for that customer that are not selected. If not provided, it returns all points campaigns vouchers for that customer, regardless of their selection status. style: form explode: true schema: type: boolean example: true - name: category_id in: query description: >- Returns all active points campaigns applicable to the specified category. style: form explode: true schema: type: integer format: int64 example: 2 - name: starting_after in: query description: >- You will receive this number on every response (on the variable **next_token_starts_after**) in order to have the next batch of elements. style: form explode: true schema: type: string example: '100' responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetAListOfScoreCampaignResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: code: invalid_request error: error message example: code: invalid_request error: error message '404': description: When is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /points/{value}: patch: tags: - points & wallet summary: Update a points/wallet campaign description: |- Updates a points campaign. **Tier 3 (Low)** — See rate limit table operationId: UpdateAPointsCampaign parameters: - name: value in: path description: Id of the campaign to be updated required: true style: simple schema: type: integer format: int64 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateADiscountCampaignRequest' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false get: tags: - points & wallet summary: Get a points campaign by id description: '**Tier 3 (Low)** — See rate limit table' operationId: getAPointsCampaignByID parameters: - name: value in: path description: >- The value which you want to search by. This value can be related to the campaign id, the voucher code, the voucher id, the static code of the coupon or the campaign history id. required: true style: simple schema: type: integer format: int64 example: 1234 - name: search_by in: query description: |- The field by which the search will be performed. * If you want to search by campaign id, you can skip this parameter or set it to `loyalty_rule_id`. * If you want to search by campaign history id (a specific delivery of the campaign) you need to set this parameter to `campaign_history_id`. * if you want to search by voucher_code you need to set this parameter to `voucher_code`. * if you want to search by voucher_id, you can skip this parameter or set it to `voucher_id`. * if you want to search by static code of the coupon, you can skip this parameter or set it to `static_code`. * If this parameter is not sent, the search will be performed by campaign id. explode: true schema: type: string example: campaign_history_id responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/ScoresResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the campaign is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the campaign is not found example: code: invalid_request error: error message example: code: invalid_request error: error message '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /points/transactions: get: tags: - points & wallet summary: Get a list of points transactions for a specific customer description: >-
The endpoint /scores/transactions is also available as a LEGACY version of this API.
A customer can earn points based on defined loyalty policies. This policies can be applied in a purchase scenario, in a signup scenario or in custom scenarios that you may want to define. Then a customer can exchange this points in order to get a discount in a purchase activity or a rewards. **In this method (score/transactions) we show all the operations that involve points. If a customer wins points, this will be reflected as a score transaction with a positive amount and if the customer spends points this will reflected as a score transaction with negative amount.** **Important**. This endpoint returns historical information. Fields like names of rewards, rules, triggers, etc. will have the value at the moment of the transaction, which could be different than the current ones if there had been any update. **Internationalization** might be used in order to return information in the expected language' **Tier 3 (Low)** — See rate limit table operationId: GetListScoreTransactions parameters: - name: include in: query description: |- Options: - If `include` is specified with **historical**, the system will search historical and internal transactions. - If `include` is specified with **only_historical**, the system will search only historcial transactions. - If it is not included, the system will search only internal transactions. style: form explode: true schema: type: string example: historical - name: customer_id in: query description: >- Mutually exclusive with `associate_id` and `customer_code`. Specify the customer for which you'd like to retrieve the scoring information. style: form explode: true schema: type: integer format: int64 example: 267 - name: customer_code in: query description: >- Mutually exclusive with `customer_id` and `associate_id`. Specify the customer for which you'd like to retrieve the scoring information. style: form explode: true schema: type: string example: a1b2c3d4 - name: associate_id in: query description: >- Mutually exclusive with `customer_id` a d `customer_code`. Specify a customer's associate for which you'd like to retrieve the scoring information. It will return the customer scoring information, no mattering which associate is implicated. style: form explode: true schema: type: integer format: int64 example: 5678 - name: starting_after in: query description: Pagination token in order to have the next batch of elements. style: form explode: true schema: type: string example: 11 - name: created_at_gt in: query description: >- If specified, it will return the transactions created after this date. The format must be [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) style: form explode: true schema: type: string example: '2006-12-31' - name: origin_type in: query description: >- Specify from what kind of transaction you'd like to retrieve the scoring information. Options: + activation - when the origin of the points is an activation of pending points + transfer - when the origin of the points is a transfer between customers + activity - when the origin of the points is an activity (purchase) + expiration - when the origin of the points is an expiration of points + subtract - when the origin of the points is a manual subtraction of points + reward - when the origin of the points is a redemption of a reward + trigger - when the origin of the points is a trigger + custom_entity - when the origin of the points is a custom entity + challenge - when the origin of the points is a challenge completion + redemption_reverted - when the origin of the points is a redemption reverted + score_payment - when the origin of the points is a payment with points (using activity_redeem endpoint) + tier - when the origin of the points is a tier upgrade style: form explode: true schema: type: string example: activation responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetListScoreTransactionsResponse' example: data: - id: 123119 type: activity created_at: '2017-12-12T13:45:22Z' amount: 64 pending_amount: 0 location_id: 334343 customer_id: 2323 origin_info: activity: id: 5873748 currency: EUR total: 192.67 creation_date: '2023-07-10T18:14:37Z' location_id: 334343 customer_id: 2323 customer: id: 2323 score: 2621 score_as_money: 0 score_available: 2621 score_available_as_money: 0 score_to_reach_cashback: 0 money_to_spend_to_reach_cashback: 0 score_threshold_cashback: 0 score_threshold_cashback_as_money: 0 money_threshold_cashback: 0 fraudulent: false lines: - order: 1 total: 192.67 quantity: 1 product_code: 22SARL01200085 original_total": 192.67 scores: - score: 64 line_order: 1 loyalty_score_id: 555253287 available_from: '2025-07-10' available_to: '2026-07-10' - score: 64 line_order: 1 loyalty_score_id: 555253287 available_from: '2025-07-10' available_to: '2026-07-10' score: 128 score_as_money: 1.28 score_used: 0 score_used_as_money: 0 score_returned_to_customer: 0 score_returned_to_customer_as_money: 0 score_returned_from_customer: 0 score_returned_from_customer_as_money: 0 coupons_desired: - all total_discount_voucher_applied: 3 total_discount_promotion_applied: 14 total_discount_applied: 17 effects: - rule_id: 555253267 line: 1, rule_name: Massive coupon discount 10% per line type: discount effect_type: percentage distribution_type: individual_items value: 1000 value_as_money: 1000 select_customers: all_customers, coupon_info: coupon_id": 100004275 coupon_name: Massive coupon discount 10% per line static_code: PROMO10 - rule_id: 555253287 line: 1, rule_name: Base rule type: points effect_type: percentage distribution_type: individual_items value: 128 value_as_money: 1.28 select_customers: loyalty available_from: '2025-07-10' available_to: '2026-07-10' scores: - loyalty_score_name: Base rule loyalty_score_id: 555253287 score: 128 available_from: '2025-07-10' available_to: '2026-07-10' - id: 1235 type: transfer created_at: '2021-12-12T13:45:22Z' amount: 50 pending_amount: 0 customer_id: 333432 origin_info: comments: because of pizza from_customer_id: 333432 to_customer_id: 2 - id: 12334 type: reward customer_id: 12321 customer_code: b7f4-e4c9f549963a created_at: '2020-12-12T13:45:22Z' amount: -500 pending_amount: 0 origin_info: reward: id: 1234 name: Reward for kids type: Physical location_id: 5000140014 - id: 1232 type: expiration customer_id: 12321 customer_code: b7f4-e4c9f549963a location_id: 12 created_at: '2021-12-12T13:45:22Z' amount: -1000 pending_amount: 0 origin_info: {} - id: 1231 type: activation customer_id: 12321 customer_code: b7f4-e4c9f549963a location_id: 12 created_at: '2021-12-12T13:45:22Z' amount: 100 pending_amount: -100 origin_info: {} - id: 12323 type: trigger created_at: '2022-12-12T13:45:22Z' amount: 100 pending_amount: 200 customer_id: 12321 customer_code: b7f4-e4c9f549963a origin_info: comments: 100 points for your birthday slug: birthday scores: - loyalty_score_name: Birthday Rule loyalty_score_id: 2 score: 100 available_from: '2022-12-12' available_to: '2023-12-12' - id: 12344 type: trigger created_at: '2022-12-12T13:45:22Z' amount: 100 pending_amount: 0 customer_id: 12321 customer_code: b7f4-e4c9f549963a origin_info: comments: is a trigger slug: slug of the trigger location_id: 704090409 scores: - loyalty_score_name: Basic Rule loyalty_score_id: 2121 score: 100 available_from: '2022-12-12' available_to: '2023-12-12' - id: 12311 type: subtract customer_id: 12321 customer_code: b7f4-e4c9f549963a location_id: 12 created_at: '2021-12-12T13:45:22Z' amount: -111 pending_amount: 0 origin_info: comments: Adjustment of points - id: 22111 type: custom_entity customer_id: 12321 customer_code: b7f4-e4c9f549963a location_id: null created_at: '2022-12-12T13:45:22Z' amount: 500 pending_amount: 0 origin_info: score: 500 slug: slug of the custom_entity scores: - loyalty_score_name: Rule/loyalty score name loyalty_score_id: 2 score: 100 available_from: '2023-12-12' available_to: '2024-12-12' - loyalty_score_name: Double points loyalty_score_id: 4 score: 400 available_from: '2023-12-12' available_to: '2024-02-12' - id: 23122 type: challenge customer_id: 12321 customer_code: b7f4-e4c9f549963a amount: 1000 pending_amount: 0 created_at: '2023-12-12T13:45:22Z' origin_info: score: 1000 challenge: id: 1234 name: Run more this month scores: - loyalty_score_name: Base points for completing a challenge loyalty_score_id: 22 score: 500 available_from: '2023-12-12' available_to: '2024-12-12' - loyalty_score_name: >- Double points during this week for completing challenge loyalty_score_id: 41 score: 500 available_from: '2023-12-12' available_to: '2024-01-12' next_token_starts_after: '234' '400': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: '' example: code: bad_request error: error message '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /customers/{value}/points: get: tags: - points & wallet summary: Retrieve the points total balance for a specific customer description: >-
The endpoint /customers/{value}/scores is also available as a LEGACY version of this API.
Returns information about the scores balance of the customer **Tier 3 (Low)** — See rate limit table operationId: GetCustomerScores parameters: - name: value in: path description: >- Could be an integer or a string. - If it is an integer, the system will search the customer by its **id**. - If it is a string, the system will search the customer by **code**. - In this case `search_param` must be specified with **code**. required: true style: simple schema: type: string example: 1234 - name: search_param in: query description: |- The param field used for the customer search. Possible options: "id" and "code" schema: type: string default: id example: code responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getcustomerscoresresponse' - example: score: 100 score_as_money: 0.1 score_available: 80 score_available_as_money: 0.08 score_to_reach_cashback: 900 money_to_spend_to_reach_cashback: 0.9 score_threshold_cashback: 1000 money_threshold_cashback: 1 score_threshold_cashback_as_money: 0.5 currency: EUR fraudulent: false example: score: 100 score_as_money: 0.1 score_available: 80 score_available_as_money: 0.08 score_to_reach_cashback: 900 money_to_spend_to_reach_cashback: 0.9 score_threshold_cashback: 1000 money_threshold_cashback: 1 score_threshold_cashback_as_money: 0.5 currency: EUR fraudulent: false '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the customer is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the customer is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /customers/{value}/points_expiring: get: tags: - points & wallet security: - api_key: [] summary: Retrieve the points about to expire for a specific customer description: >-
The endpoint /customers/{value}/scores_expiring is also available as a LEGACY version of this API.
Returns a list of expiring scores given a customer grouped by date, order by date asc. **Tier 3 (Low)** — See rate limit table operationId: GetCustomerExpiringScores parameters: - name: value in: path description: |- Could be an integer or a string. - If `search_param` is specified with **code** and is a valid string value, the system will search the customer by **code**. - If it is an integer, the system will search the customer by its **id**. - If `search_param` is specified with **associate_id** and is an integer, the system will search the customer by **associate_id**. required: true style: simple schema: type: string example: 1234 - name: date in: query description: >- The param field used for the date. Customer scores can be searched with a maximum of 60 days. If the date is omitted or before the current date, it will be automatically set to the current date + 60 days. required: false schema: type: string example: '2023-04-01' - name: search_param in: query description: |- The param field used for the customer search. Possible options: "id", "code", "associate_id" schema: type: string default: id example: code responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetCustomerExpiringScoresResponse' - example: - data: - score_available: 210 score_available_as_money: 4 currency: EUR expiration_date: '2023-05-31T00:00:00Z' - score_available: 420 score_available_as_money: 8 currency: EUR expiration_date: '2023-06-30T00:00:00Z' example: data: - score_available: 210 score_available_as_money: 4 currency: EUR expiration_date: '2023-05-31T00:00:00Z' - score_available: 420 score_available_as_money: 8 currency: EUR expiration_date: '2023-06-30T00:00:00Z' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the customer is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the customer is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /points/redeem: post: tags: - points & wallet summary: Redeem points from balance description: >-
The endpoint /scores/subtract is also available as a LEGACY version of this API.
**This method allows to subtract points from a customer balance.** > [Idempotence](https://streaming-api.doc.loyal.guru/#section/HTTP-API/Idempotent-Requests) action allowed **Tier 3 (Low)** — See rate limit table operationId: SubtractPointsFromACustomer parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/SubtractPointsFromACustomerRequest' - example: customer_id: 100005 customer_code: b7f4-e4c9f549963a amount: 100 comments: Subtraction done due to an adjustment example: customer_id: 100005 customer_code: b7f4-e4c9f549963a amount: 100 comments: Subtraction done due to an adjustment of your balance required: true responses: '200': description: Customer's scores successfully subtracted. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/SubtractPointsFromACustomerResponse' - description: Customer's scores successfully subtracted. example: customer: id: 100005 code: b7f4-e4c9f549963a score: 2000 score_available: 1000 score_used: 100 score: 2000 score_available: 1000 example: customer: id: 100005 code: b7f4-e4c9f549963a score: 2000 score_available: 1000 score_used: 100 score: 2000 score_available: 1000 '400': description: |- **Posible errors:** When the any of the parameters is not valid or missing. When the customer is not found. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: |- **Posible errors:** When the any of the parameters is not valid or missing. When the customer is not found. example: code: invalid_request error: error message example: code: invalid_request error: error message '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /points/redeem_cart: post: tags: - points & wallet summary: Redeem points from balance for a specific cart description: >-
The endpoint /scores/activity_redeem is also available as a LEGACY version of this API.
A customer can earn points based on defined loyalty policies. This policies can be applied in a purchase scenario, in a signup scenario or in custom scenarios that you may want to define. Then a customer can exchange this points by currencies in order to get a discount in a purchase activity. A customer can Redeem an amount of points related to an activity. It's **important** to highlight that the Activity (ticket) must exist first. There are multiple checks that are necessary when validating a redemption of points, such as: - Customer exists - Customer is not flagged as potentially fraudulent - Enough points to redeem > [Idempotence](https://streaming-api.doc.loyal.guru/#section/HTTP-API/Idempotent-Requests) action allowed **Tier 2 (Moderate)** — See rate limit table operationId: ActivityRedeem parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/ActivityRedeemRequest' - example: activity_id: 12345 customer_id: 1234 location_id: 12 score: 100 example: activity_id: 12345 customer_id: 1234 location_id: 12 amount: 100 required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/ActivityRedeemResponse' - example: customer: id: 8223342 code: 8223a score: 200 score_available: 100 score_used: 100 score: 200 score_available: 100 example: customer: id: 8223342 code: 8223a score: 200 score_available: 100 score_used: 100 score: 200 score_available: 100 '400': description: |- **Posible errors:** - When any of the parameters is not valid or missing. - When the customer is not found. - When the customer does not have enough points. - When the customer is marked as potentially fraudulent headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: invalid_request error: 'error finding activity by code: activity not found' - code: invalid_request error: 'error finding activity by id: activity not found' - code: invalid_request error: 'error finding location by code: location not found' - code: invalid_request error: 'error finding location by id: location not found' - code: invalid_request error: 'error finding customer by code: customer not found' - code: invalid_request error: 'error finding customer by id: customer not found' - code: invalid_request error: >- location_code is colliding with another mutually exclusive field - code: invalid_request error: >- location_id is colliding with another mutually exclusive field - code: invalid_request error: >- customer_id is colliding with another mutually exclusive field - code: invalid_request error: >- customer_code is colliding with another mutually exclusive field - code: invalid_request error: >- activity_code is colliding with another mutually exclusive field - code: invalid_request error: activity_id is required - code: invalid_request error: location_id is required - code: invalid_request error: customer_id is required - code: invalid_request error: amount is required - code: invalid_request error: Not enough points - code: invalid_request error: customer can not redeem points '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /points/transfer: post: tags: - points & wallet summary: Transfer points from one customer to another description: >-
The endpoint /scores/transfer is also available as a LEGACY version of this API.
A customer can earn points based on defined loyalty policies. This policies can be applied in a purchase scenario, in a signup scenario or in custom scenarios that you may want to define. Then a customer can exchange this points by currencies in order to get a discount in a purchase activity. Also a customer can exchange points by rewards.Transfer points from one customer to another. Keep in mind that some points earned in certain policies are not ready for transfers, and that suspended/inactive customers can not transfer to another customers or from another customers. Also, keep in mind that one customer can not transfer more points that the total sum of the customer points. If 'allow_partial=true' parameter is provided then if the customer tries to transfer an amount of points higher than the available amount, then all available points will be transfered. **Tier 3 (Low)** — See rate limit table operationId: Transfer parameters: [] requestBody: description: '' content: application/json: schema: oneOf: - $ref: '#/components/schemas/TransferRequestCustomerID' - $ref: '#/components/schemas/TransferRequestCustomerCode' examples: TransferRequestCustomerID: value: score: 24 from_customer_id: 9876666 to_customer_id: 67788876 comments: Some comments allow_partial: true TransferRequestCustomerCode: value: score: 24 from_customer_code: 9876666a to_customer_code: 67788876a comments: Some comments allow_partial: true required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/TransferResponse' - example: from_customer_id: 1150524070032999000 to_customer_id: 790178790032933400 score: 100000 comments: Some comments requested_scores: 200000 example: from_customer_id: 1150524070032999000 to_customer_id: 790178790032933400 score: 100000 comments: Some comments requested_scores: 200000 '400': description: When any of the request parameters is invalid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the request parameters is invalid or missing. example: code: invalid_request error: error message '403': description: When any of the request parameters is forbidden. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the request parameters is forbidden. example: code: forbidden error: customer can not transfer points '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message deprecated: false /cashbacks: get: tags: - points & wallet summary: Get cashback conversion by location description: '**Tier 3 (Low)** — See rate limit table' operationId: GetCashbacksBasedOnALocation parameters: - name: location_id in: query description: >- A integer representing a location. - If the the **location_id** is a valid location, returns the cashback for this location, otherwise returns a *404* required: true style: form explode: true schema: type: integer format: int64 example: 1234 responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getcashbacksbasedonalocationresponse' - example: cashback: 0.005 currency: EUR example: cashback: 0.005 currency: EUR '400': description: When the parameter is not **location_id**. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getcashbacksbasedonalocationresponse1' - description: When the parameter is not **location_id**. example: code: invalid_request error: invalid location example: code: invalid_request error: invalid location '404': description: When the **location_id** is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the **location_id** is not found example: code: location_not_found error: location not found example: code: location_not_found error: location not found deprecated: false /cashback_thresholds: get: tags: - points & wallet summary: Retrieve a list of cashback threholds? description: '**Tier 3 (Low)** — See rate limit table' operationId: GetAListOfCashbackThresholds responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CashbackThresholdDataList' - example: data: - country: ES currency: EUR score: 100 money_representation: 12.5 - country: FR currency: EUR score: 400 money_representation: 10 '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /rewards: get: tags: - rewards summary: Get a list of Rewards description: >- Endpoint to list all the rewards available in different scenarios you may need (**check query parameters**). For example: - Create a **Customer Rewards Catalogue**. When filtered by customer, this endpoint returns all the rewards available to the customer based on their country. The can_redeem field in the response indicates whether or not the customer can redeem each reward. - To list all rewards available in a specific country or store. - To list upcoming rewards that are expected to be available soon. **Internationalisation** can be used to return the reward name and description in the expected language. For example, if the end customer's preferred language is English, send Accept-Language = "EN" and every multi-language field of the reward output will be in English. Check out the following links that can help you: - How to build a rewards catalogue: [Link](https://loyal-guru.atlassian.net/servicedesk/customer/portal/9/topic/740edbd8-5048-48d9-812f-25d391b96682/article/3029958671) - General information about rewards: [Link](https://loyal-guru.atlassian.net/servicedesk/customer/portal/9/topic/740edbd8-5048-48d9-812f-25d391b96682/article/3092906019) The JSON response schema can be checked below **Tier 2 (Moderate)** — See rate limit table operationId: GetAListOfRewards parameters: - name: location_id in: query description: >- Filter rewards available in certain location. If both `location_id` and `location_code` are provided, only `location_id` will be considered. Mutually exclusive with `countries`. style: form explode: true schema: type: integer format: int64 example: 1234 - name: location_code in: query description: >- Filter rewards available in certain location. If both `location_id` and `location_code` are provided, only `location_id` will be considered. Mutually exclusive with `countries`. style: form explode: true schema: type: string example: abc - name: customer_id in: query description: >- ID of the customer. Mutually exclusive with `customer_code`. Filter rewards defined for the country of the customer. If this value (or customer code) is sent as a parameter, it will return all the rewards available in the customer's country of registration. What indicates whether or not the customer can redeem each reward is the field called `can_redeem` available in the response. style: form explode: true schema: type: integer format: int64 example: 12345 - name: customer_code in: query description: >- Code of the customer. Mutually exclusive with `customer_id`. Filter rewards defined for the country of the customer. If this value (or customer id) is sent as a parameter, it will return all the rewards available in the customer's country of registration. What indicates whether or not the customer can redeem each reward is the field called `can_redeem` available in the response. style: form explode: true schema: type: string example: 12345a - name: countries in: query description: >- Countries where the reward is available. Mutually exclusive with `location_id` or `location_code` and `customer_id` or `customer_code`. For more than one country, example: countries=ES&countries=FR . It will return rewards for Spain **OR** France style: form explode: true schema: type: array items: type: string example: - ES - name: status in: query description: >- Filter rewards according to their status. All rewards by default. Options: - active: Will return only rewards with status = active - inactive: Will return only rewards with status = inactive - available: Will return available rewards considering: status = active, available_from <= today >= available_to - upcoming: Will return upcoming rewards considering: status = active, available_from > today style: form explode: true schema: type: string example: active - name: starting_after in: query description: >- You will receive this number on every response (on the variable **next_token_starts_after**) in order to have the next batch of elements. style: form explode: true schema: type: string example: '100' - name: store in: query description: >- Used when you need a better personalisation of the rewards catalogue for a particular customer, taking into account the rewards available in a particular store. For example, if store=registration, the result will include rewards available in the customer's registration store plus all other rewards available in the customer's country. Makes sense only if `customer_id` or `customer_code` is included as part of the params. Options: - registration - Filters by registration_location_id of the customer - favourite (UPCOMING) - usual (UPCOMING) **Mutually exclusive with `location_id` and `location_code`** style: form explode: true schema: type: string example: registration - name: type in: query description: >- Type of the reward. Possible types are: 'physical', 'code', 'donation', 'digital', 'downloadable', 'coupon', 'free_delivery', 'voucher', 'wallet' style: form explode: true schema: type: string example: donation - name: redemption_type in: query description: >- Optional parameter. Add the parameter filter to return either 'manual' rewards (default behaviour, not needed to include it) or use redemption_type = 'loyalty_rule' to return rewards that can only be redeemed by loyalty rule conditions. redemption_type = “loyalty_rule“ filter is mutually exclusive with `location_id/code`, `customer_id/code`, `countries`, `status` and `store`. It only works with parameters `type` and `starting_after`. style: form explode: true schema: type: string example: manual - name: restricted_by in: query description: >- If this is sent as part of the request, the response will exclude those rewards that the customer **can not redeem** based on the parameter. By default the endpoint return everything. Possible options: - tiers: if “tiers“ is sent, exclude rewards that can not be redeemed by the customer's tier - points: if “points“ is sent, exclude rewards that can not be redeemed because the customer has not enough points - redeemed_chances: if “redeemed_chances“ is sent, exclude rewards that can not be redeemed because the customer has exceeded the rewards limits. - stock: if “stock“ is sent, exclude rewards that can not be redeemed because the reward has no more stock available **More than one option can be sent at the same time.** For example you can send restricted_by=tiers&restricted_by=points&restricted_by=stock Makes sense only if `customer_id` or `customer_code` is included as part of the params. style: form explode: true schema: type: array items: type: string example: - tiers - points responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetAListOfRewardsResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: code: invalid_request error: error message example: code: invalid_request error: error message '404': description: When the location_id is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the location_id is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /rewards/{id}: get: tags: - rewards summary: Get a Reward description: '**Tier 3 (Low)** — See rate limit table' operationId: GetARewardByID parameters: - name: id in: path description: The ID of the reward. required: true style: simple schema: type: integer format: int64 example: 1234 - name: customer_id in: query description: >- ID of the customer. Mutually exclusive with `customer_code`. If this value (or customer code) is sent as a parameter, it will return information about the relationship between the reward and the customer (extra fields). What indicates whether or not the customer can redeem each reward is the field called `can_redeem` available in the response. style: form explode: true schema: type: integer format: int64 example: 12345 - name: customer_code in: query description: >- Code of the customer. Mutually exclusive with `customer_id`. If this value (or customer id) is sent as a parameter, it will return information about the relationship between the reward and the customer (extra fields). What indicates whether or not the customer can redeem each reward is the field called `can_redeem` available in the response. style: form explode: true schema: type: string example: 12345a responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetARewardByIDResponse' example: id: 319 name: Red umbrella description: Exclusive red Umbrella points: 100 flexible_score_allowed: true available_from: '2023-01-01' available_to: '2025-12-31' status: active image_url: https://www.testimage.com/imagereward extra_money: 2.5 currency: EUR countries: - ES - UY - AR is_coupon: true categories: - id: 6 name: Promotions taxonomy_slug: tags image_url: https://www.testimage.com/imagecategory coupon: id: 123 key: 'discountkeyreferencing internal promo ' max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash affectation: activity features: - id: 1234 taxonomy_slug: a_slug product_ids: - 5 - 11 partner: id: 1 name: Airlines LG description: partnership with airline image_url: https://www.testimage.com/imagePartner total_stock: 1000 redeem_chances: num_total redeem_times: 5 available_stock: 890 validity_duration_number: 60 validity_duration_unit_option: days validity_duration_type: relative can_redeem: true redemptions_quantity: 1 redemption_type: manual '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the reward is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the reward is not found example: code: invalid_request error: error message example: code: invalid_request error: error message '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message deprecated: false /rewards/{id}/redeem: post: tags: - rewards summary: Redeem a Reward description: >- This is the endpoint necessary to use when a customer is going to redeem a reward. A reward redemptions means that in order to get a reward, needed points must be subtracted from the total points of the customer. There are multiple checks that are necessary when validating a redemption, such as: - Customer is not flagged as potentially fraudulent - Enough points to redeem the reward - Availability of the reward (in terms of dates and status) - Availability of the reward in the customer's country - Sufficient stock available - Limits defined in terms of how many times a reward can be redeemed by customer - Reward available for customer's tier If all the necessary conditions are not met, an error will be returned. **Tier 3 (Low)** — See rate limit table operationId: RedeemAReward parameters: - name: id in: path description: ID of the reward to redeem required: true style: simple schema: type: integer format: int64 example: 12 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/RedeemARewardRequest' - example: location_id: 211 customer_id: 8223342 score_overwrite: 200 process_actions: false source: api required: true responses: '200': description: >- Success, server completed the request as expected, so the reward has been redemeed. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/RedeemARewardResponse' - example: customer: id: 8223342 code: 8223a score: 100 score_available: 60 score_used: 200 score: 100 score_available: 60 redemption_id: 12032 code: 8234ABR '400': description: >- When the reward is out of stock, codes are used up, or parameters are missing or invalid. headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: invalid_request error: no more redemptions allowed for this reward - code: invalid_request error: >- location_code is colliding with another mutually exclusive field - code: invalid_request error: >- location_id is colliding with another mutually exclusive field - code: invalid_request error: >- customer_id is colliding with another mutually exclusive field - code: invalid_request error: >- customer_code is colliding with another mutually exclusive field - code: invalid_request error: >- associate_id is colliding with another mutually exclusive field - code: invalid_request error: >- reward with an associated coupon does not allow flexible score - code: invalid_request error: reward not redeemable with score_overwrite - code: invalid_request error: reward is not available for customer's tier - code: invalid_request error: customer can not redeem points - code: invalid_request error: reward is not available in location - code: invalid_request error: error finding reward_locations - code: invalid_request error: reward is not available - code: invalid_request error: reward is not active - code: customer_inactive error: customer is inactive '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code '404': description: Not found, the requested includes a resource that does not exist. headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: not_found error: reward with id {id} not found - code: not_found error: customer not found - code: not_found error: customer not found using associateId '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code deprecated: false /rewards/transactions: get: tags: - rewards summary: Get a list of reward transactions description: >-
The endpoint /redemptions is also available as a LEGACY version of this API.
Returns a list of redemptions by customer or location that you can use for different use cases (**check query parameters**). For example: - List all rewards redeemed by a specific customer when filtering by customer_id or customer_code, including additional information available in the JSON Schema response below. - List all rewards redeemed at a specific location or store - List all redemptions within a specified time period. It is Ordered from the newest to the oldest redemption. If `customer_code` and `customer_id` are present, only `customer_id` is going to be used. If `location_code` and `location_id` are present, only `location_id` is going to be used **Tier 3 (Low)** — See rate limit table operationId: GetAListOfRedemptions parameters: - name: location_id in: query description: >- Specify the location for which you'd like to retrieve the redemptions data. style: form explode: true schema: type: integer format: int64 example: 267 - name: location_code in: query description: >- Specify the location for which you'd like to retrieve the redemptions data. style: form explode: true schema: type: string example: 43431asd-g87 - name: customer_id in: query description: >- Specify the customer for which you'd like to retrieve the redemptions data. style: form explode: true schema: type: integer format: int64 example: 23211 - name: customer_code in: query description: >- Specify the customer for which you'd like to retrieve the redemptions data. style: form explode: true schema: type: string example: 267a2133-2232 - name: status in: query description: |- Specify the status of the redemptions you want to retrieve. Options: - available: It returns those redemptions that are available (Default value). - reverted: It returns those redemptions that were reverted. - all: No filter is applied, it returns all the redemptions (available + reverted). style: form explode: true schema: type: string example: available - name: starting_after in: query description: >- You will receive this number on every response ( on the variable **next_token_starts_after** ) in order to have the next batch of elements style: form explode: true schema: type: string example: '124' responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getalistofredemptionsresponse' - example: data: - id: 1456 created_at: '2022-12-13 13:00:00' customer_id: 1232211 customer_code: b7f4-e4c9f549963a location_id: 289 reward_id: 123 score_expense: 150 code: 9034ABD status: available source: api - id: 789 created_at: '2018-12-20 20:00:00' customer_id: 1232211 customer_code: b7f4-e4c9f549963a location_id: 345 reward_id: 124 score_expense: 200 origin_type: challenge origin_id: '1121' loyalty_rule_id: 1 status: available source: challenge next_token_starts_after: '1' example: data: - id: 1456 created_at: '2022-12-13 13:00:00' customer_id: 1232211 customer_code: b7f4-e4c9f549963a location_id: 289 reward_id: 123 score_expense: 150 code: 9034ABD status: available source: api - id: 789 created_at: '2018-12-20 20:00:00' customer_id: 1232211 customer_code: b7f4-e4c9f549963a location_id: 345 reward_id: 124 score_expense: 200 origin_type: challenge origin_id: '1121' loyalty_rule_id: 1 status: available source: challenge next_token_starts_after: '1' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /rewards/transactions/{id}/rollback: post: tags: - rewards summary: Revert a reward redemption description: >-
The endpoint /redemptions/{id}/rollback is also available as a LEGACY version of this API.
This endpoint is designed to revert a customer´s redemption — particularly useful if a follow-up action, like calling a third-party API, fails after the redemption is completed. **Important:** The reversal **should occur within a few seconds after the redemption to ensure point integrity**, preventing conflicts from potential returns, additional redemptions, or other transactions happening in the meantime. **Tier 3 (Low)** — See rate limit table operationId: RevertARedemption parameters: - name: id in: path description: ID of the redemption to revert required: true style: simple schema: type: integer format: int64 example: 12 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/RevertARedemptionRequest' - example: status_detail: The item is out of stock required: true responses: '200': description: >- Success, server completed the request as expected, so the reward has been redemeed. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/RevertARedemptionResponse' - example: redemption_id: 2324321 status: reverted status_detail: The item is out of stock '400': description: Bad Request headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: invalid_request error: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code '404': description: Not found, the requested includes a resource that does not exist. headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: not_found error: redemption not found - code: not_found error: customer not found '409': description: When the redemption has been already reverted headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: conflict error: redemption not revertible '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code deprecated: false /challenges: get: tags: - challenges summary: Get a list of Challenges description: |- Get a list of challenges **Tier 3 (Low)** — See rate limit table operationId: GetAListOfChallenges parameters: - name: country in: query description: Country where the challenge is available. style: form explode: true schema: type: string example: ES - name: type in: query description: Type of challenge for filtering. style: form explode: true schema: type: string example: sports - name: starting_after in: query description: >- You will receive this number on every response ( on the variable **next_token_starts_after** ) in order to have the next batch of elements style: form explode: true schema: type: string example: true@11 responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetAListOfChallengesResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: code: invalid_request error: error message example: code: invalid_request error: error message '404': description: When the location_id is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the location_id is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message /challenges/{id}: get: tags: - challenges summary: Get a challenge description: '**Tier 3 (Low)** — See rate limit table' operationId: GetAChallengeByID parameters: - name: id in: path description: The ID of the challenge. required: true style: simple schema: type: integer format: int64 example: 1234 responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/GetAChallengeByIDResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the reward is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the reward is not found example: code: invalid_request error: error message example: code: invalid_request error: error message '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: code: server_error error: error message example: code: server_error error: error message /customers/{value}/challenges: get: tags: - challenges summary: Get a list challenges for a customer description: >- Returns the entire challenge catalogue available to the customer, taking into account all challenges that the customer could participate in and all challenges that the customer is already participating in, including the current status or progress of these challenges. Only challenges with status = active, available_to >= current date, and available in the customer's country will be returned. Enrolled challenges will be returned first in the list order. **Check out the following links that can help you:** - How to build a challenge progress bar: [Link](https://loyal-guru.atlassian.net/servicedesk/customer/portal/9/topic/5d998dae-6e98-43a4-a99c-73f450124d12/article/3025698821) - How to create a challenge: [Link](https://loyal-guru.atlassian.net/servicedesk/customer/portal/9/topic/5d998dae-6e98-43a4-a99c-73f450124d12/article/2660630572) **Tier 2 (Moderate)** — See rate limit table operationId: GetCustomerChallenges parameters: - name: value in: path description: >- Could be an integer or a string. - If it is an integer, the system will search the customer by its **id**. - If it is a string, the system will search the customer by **code**. - In this case `search_param` must be specified with **code**. required: true style: simple schema: type: string example: 1234 - name: search_param in: query description: |- The param field used for the customer search. Possible options: "id" and "code" schema: type: string default: id example: code - name: only_enrolled in: query description: >- * When only_enrolled = true → return the list of challenges in which the customer is already participating (both enrolled on demand or subscribed by default). * When only_enrolled = false or omitted → return the full list of challenges available for the country of the customer (subscribed and not subscribed to). style: form explode: true schema: type: boolean example: true - name: use_display_dates in: query description: >- * When use_display_dates = true → return the list of challenges where the current date is between the display_from and display_to dates. * When use_display_dates = false or omitted → return the full list of challenges independent of the display dates based on the available_to date. style: form explode: true schema: type: boolean example: true - name: type in: query description: Type of challenge for filtering. style: form explode: true schema: type: string example: sports - name: starting_after in: query description: >- You will receive this number on every response ( on the variable **next_token_starts_after** ) in order to have the next batch of elements style: form explode: true schema: type: string example: true@11 responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomerChallengesResponse' '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the customer is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the customer is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /customers/{value}/challenges/{id}: get: tags: - challenges summary: Get a challenge for a customer description: >- Returns the challenge related to the customer, including the current status or progress of this challenge. Only challenge with status = active, available_to >= current date, and available in the customer's country will be returned. **Tier 2 (Moderate)** — See rate limit table operationId: GetCustomerChallenge parameters: - name: value in: path description: >- Could be an integer or a string. - If it is an integer, the system will search the customer by its **id**. - If it is a string, the system will search the customer by **code**. - In this case `search_param` must be specified with **code**. required: true style: simple schema: type: string example: 1234 - name: id in: path description: The ID of the achievement. required: true style: simple schema: type: integer format: int64 example: 1234 - name: search_param in: query description: |- The param field used for the customer search. Possible options: "id" and "code" schema: type: string default: id example: code responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomerChallengeResponse' example: data: - id: 11 name: Run more this month description: Get extra points for running more this month! attribute_value: 70 attribute_id: 10 last_execution_time: '2023-11-23T14:33:00Z' countries: - ES expires_at: '2023-11-25T14:33:00Z' available_from: '2023-07-10' available_to: '2024-12-31' display_from: '2023-07-01' display_to: '2025-01-15' challenge_type: Sports image_url: https://www.testimage.com/imagechallenge image_file_name: imagechallenge.png open_to_all: false max_enrollments: 1700 current_enrollments: 220 enrolled: true partner: id: 1 name: Airlines LG description: partnership with airline image_url: null attribute_data_period_type: current_week attribute_period_from: '2024-02-26' attribute_period_to: '2024-03-03' structure: - level: 1 name: Run 60 kms threshold: 60 reached: true won_at: '2023-11-23T14:33:00Z' prizes: - type: points rule_id: 12345 rule_name: 100 points extra effects: >- {"type": "direct_value", "value": 100, distribution": "total"} - type: coupon coupon_info: coupon_id: 4322211 coupon_name: 10% off on beverages coupon_description: Get 10% off on all beverages for the next 7 days - type: discount rule_id: 54321 rule_name: 15% discount on next purchase effects: >- {"type": "percentage", "value": 15, distribution": "total"} awards: - amount: 1000 type: score - reward_id: 12 reward_name: Free Netflix suscription for 3 months loyalty_score_id: 19099 type: reward - reward_id: 111 reward_name: 25% discount gym loyalty_score_id: 12222 type: reward '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the customer is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the customer is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /challenges/{id}/enroll: post: tags: - challenges summary: Enroll to a challenge description: >- This is the endpoint necessary to use when a customer is going to enroll to a challenge in order to participate in it. There are multiple checks that are necessary when validating a enrollment, such as: - The challenge allows enrollments. - Availability of the challenge (in terms of dates and status). Enrollment might be done before it starts but not after it ended. - Availability of the challenge in the customer's country. - Number of maximum enrollments available. - Customer is already enrolled. If all the necessary conditions are not met, an error will be returned. **Tier 3 (Low)** — See rate limit table operationId: EnrollAChallenge parameters: - name: id in: path description: ID of the challenge to enroll required: true style: simple schema: type: integer format: int64 example: 12 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/EnrollAChallengeRequest' required: true responses: '200': description: >- Success, server completed the request as expected, so the challenge has been enrolled. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/EnrollAChallengeResponse' '400': description: >- When the challenge can not be enrolled, or parameters are missing or invalid. headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: invalid_request error: customer_id or customer_code is required - code: invalid_request error: customer is inactive - code: invalid_request error: customer is already enrolled in the challenge - code: invalid_request error: challenge is not available in the customer's country - code: invalid_request error: challenge is not available for enrollment - code: invalid_request error: challenge does not allow more enrollments - code: invalid_request error: challenge is inactive '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code '404': description: Not found, the requested includes a resource that does not exist. headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' example: - code: not_found error: challenge not found - code: not_found error: customer not found - code: not_found error: 'error finding customer by ID: customer not found' '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code deprecated: false /coupons: post: tags: - campaign coupons summary: Create a new Coupon description: >- A coupon is defining a discount that is applicable when a customer presents a voucher ( a child from this coupon ). A very important element of a coupon is its "key", a key is the element that your POS system will understand in order to apply certain discount. **Tier 3 (Low)** — See rate limit table operationId: CreateANewCoupon parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewCouponrequest' - example: id: 1234 name: Coupon discount 50% description: Discount on meat available_from: '2016-01-01' available_to: '2016-02-01' key: '1234' created_at: '2016-01-01T12:00:00Z' location_ids: - 1 - 2 priority: 1 external_id: '1' example: id: 1234 name: Coupon discount 50% description: Discount on meat available_from: '2016-01-01' available_to: '2016-02-01' key: '1234' created_at: '2016-01-01T12:00:00Z' location_ids: - 1 - 2 priority: 1 external_id: '1' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /coupons/{id}: patch: tags: - campaign coupons summary: Update a Coupon description: >- A coupon is defining a discount that is applicable when a customer presents a voucher ( a child from this coupon ). A very important element of a coupon is its "key", a key is the element that your POS system will understand in order to apply certain discount. **Tier 3 (Low)** — See rate limit table operationId: UpdateACoupon parameters: - name: id in: path description: ID of the coupon required: true style: simple schema: type: integer format: int64 example: 12 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaCouponrequest' - example: name: Coupon discount 50% description: I'm a coupon key: '1234' available_from: '2016-01-01' available_to: '2016-02-01' created_at: '2015-12-01' priority: 1 external_id: '1' example: name: Coupon discount 50% description: I'm a coupon key: '1234' available_from: '2016-01-01' available_to: '2016-02-01' created_at: '2015-12-01' priority: 1 external_id: '1' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaCouponresponse' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - campaign coupons summary: Delete a Coupon description: >- A coupon is defining a discount that is applicable when a customer presents a voucher ( a child from this coupon ). A very important element of a coupon is its "key", a key is the element that your POS system will understand in order to apply certain discount. **Tier 3 (Low)** — See rate limit table operationId: DeleteAcoupon parameters: - name: id in: path description: ID of the coupon required: true style: simple schema: type: integer format: int64 example: 12 - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/DeleteaCouponresponse' - example: status: success example: status: success deprecated: false /customers/{id}/vouchers: get: tags: - campaign vouchers summary: Get a list of vouchers description: >- Get an array of all vouchers belonging to the customer according to the filters. When set by parameter "location_info=true" the fields "location_ids" and "feature_locations" fields be returned. When a voucher has a product allocation related to an internal category, by default the POS does receive the product IDs (*product_ids*) belonging to that internal category. For the POS to also receive the external product category, it must be configured in the company configuration. Additionally, 'purchased_product_ids' will provide information about the purchased products in relation to a specific campaign. Please be aware that the list is paginated **Tier 2 (Moderate)** — See rate limit table operationId: GetAListOfVouchers parameters: - name: id in: path description: '' required: true style: simple schema: type: string - name: location_id in: query description: '' required: false schema: type: string - name: location_code in: query description: >- Location code. Both location_id and location_code can be used, but if both are sent, location_id has priority. required: false schema: type: string - name: status in: query description: |- Specify the voucher status to filter. The possible values are: + available + expired + pending + cancelled + redeemed (Returns vouchers that have used all the available redemptions) + printed + available_to_print (Returns vouchers in the printing period (both pending or printed status)) required: false schema: type: string - name: location_info in: query description: >- Specify the inclusion of the "location_ids" and "feature_locations" fields: + true + false required: false schema: type: boolean - name: redemption_dates in: query description: >- Show the redemption dates of the vouchers. When this flag is activated redeemed vouchers will be shown as well. The possible values are: + true + false required: false schema: type: boolean - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json x-codeSamples: - lang: URL source: >- /customers/12345/vouchers?location_id=6789&location_code=LOC-ABC&status=available&location_info=true&redemption_dates=true responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/Getalistofvouchersresponse' '400': description: >- Location id not valid. This will happen when the location_id parameter is not a number. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getalistofvouchersresponse1' - description: >- Customer id not valid. This will happen when the id parameter is not a number. example: code: invalid_request error: cannot parse id example: code: invalid_request error: cannot parse id '403': description: Customer account is not active headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /customers/{id}/vouchers/selected: get: tags: - campaign vouchers summary: Get a list of selected vouchers description: >- Get an array of available selected vouchers belonging to the customer in the location. If the optional date parameter is provided, then the endpoint returns a list of vouchers available for the specified date. When set by parameter "location_info=true" the fields "location_ids" and "feature_locations" fields be returned. When a voucher has a product allocation related to an internal category, by default the POS does receive the product IDs (*product_ids*) belonging to that internal category. For the POS to also receive the external product category, it must be configured in the company configuration. Additionally, 'purchased_product_ids' will provide information about the purchased products in relation to a specific campaign. **Tier 2 (Moderate)** — See rate limit table operationId: GetAListOfSelectedVouchers parameters: - name: id in: path description: '' required: true style: simple schema: type: string - name: location_id in: query description: location_id OR location_code is required. required: true schema: type: string - name: location_code in: query description: location_id OR location_code is required. required: true schema: type: string - name: location_info in: query description: >- Specify the inclusion of the "location_ids" and "feature_locations" fields: + true + false required: false schema: type: boolean - name: redemption_dates in: query description: >- Show the redemption dates of the vouchers. When this flag is activated redeemed vouchers will be shown as well. The possible values are: + true + false required: false schema: type: boolean - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json x-codeSamples: - lang: URL source: >- /customers/12345/vouchers/selected?location_id=6789&location_code=LOC-ABC&location_info=true&redemption_dates=true responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/Getalistofvouchersresponse' '400': description: Incorrect date format. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getalistofselectedvouchersresponse' - description: >- Customer id not valid. This will happen when the id parameter is not a number. example: code: invalid_request error: cannot parse id example: code: invalid_request error: cannot parse id '403': description: Customer account is not active headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/{code}: get: tags: - campaign vouchers summary: Get a voucher description: >- Vouchers represent the association between a coupon and a customer. When a voucher has a product allocation related to an internal category, by default the POS does receive the product IDs (*product_ids*) belonging to that internal category. For the POS to also receive the external product category, it must be configured in the company configuration. Additionally, 'purchased_product_ids' will provide information about the purchased products in relation to a specific campaign. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration. **Tier 3 (Low)** — See rate limit table operationId: GetAVoucher parameters: - name: code in: path description: '' required: true style: simple schema: type: string responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/Getavoucherresponse' '400': description: >- Customer id not valid. This will happen when the id parameter is not a number. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getavoucherresponse1' - description: >- Customer id not valid. This will happen when the id parameter is not a number. example: code: invalid_request error: cannot parse id example: code: invalid_request error: cannot parse id '403': description: Customer account is not active headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers//{code}: get: tags: - campaign vouchers summary: Validate a voucher description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration. When a voucher has a product allocation related to an internal category, by default the POS does receive the product IDs (*product_ids*) belonging to that internal category. For the POS to also receive the external product category, it must be configured in the company configuration. Additionally, 'purchased_product_ids' will provide information about the purchased products in relation to a specific campaign. This endpoint checks if a certain voucher is valid for certain customer and location. When is valid, it returns the `key` is the code that your POS system will understand and will use in order to apply a particular discount. Is a number that was previously defined in your system outside Loyal Guru. - **IMPORTANT**: You'll need the `voucher_code` on the `/vouchers/redeem` endpoint ( and if you want to exclude several vouchers from printing you will need it too on the `vouchers/print` endpoint ) **Tier 2 (Moderate)** — See rate limit table operationId: ValidateAVoucher parameters: - name: code in: path description: Code of the voucher. required: true style: simple schema: type: string example: '27454637261254' - name: customer_id in: query description: id of the customer style: simple required: true schema: type: integer format: int64 example: 12345 - name: location_id in: query description: id of the location style: simple required: true schema: type: integer format: int64 example: 123 responses: '200': description: Successful response headers: {} content: application/json: schema: $ref: '#/components/schemas/Vouchervalidationresponse' '400': description: >- Customer id not valid. This will happen when the id parameter is not a number. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getavoucherresponse1' - description: When the any of the parameters is not valid or missing. example: code: invalid_request error: error message example: code: invalid_request error: error message '403': description: Customer account is not active headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '404': description: >- Customer id not valid. This will happen when the id parameter is not a number. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Vouchervalidationresponse1' - description: >- Voucher not found, customer not found or voucher does not belongs to the customer. example: code: voucher_not_found error: >- Voucher not found, customer not found or voucher does not belongs to the customer. example: code: voucher_not_found error: >- Voucher not found, customer not found or voucher does not belongs to the customer. '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/redeem: post: tags: - campaign vouchers summary: Redeem a list of vouchers description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration.Send some vouchers in order to mark them as used, so they can not be used anymore. **Notice:** You can avoid this request if your are using the "create activity" endpoint passing the used vouchers as parameters. **Tier 3 (Low)** — See rate limit table operationId: RedeemAListOfVouchers parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/Redeemalistofvouchersrequest' - example: activity_id: 1234 vouchers: - code: '1234' discount: 1267 line_order: 1 product_id: 2 example: activity_id: 1234 vouchers: - code: '1234' discount: 1267 line_order: 1 product_id: 2 required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/rollback: post: tags: - campaign vouchers summary: Rollback a list of vouchers description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration. This endpoint allows you to rollback vouchers that have been redeemed. When a voucher is rolled back, it returns to its previous state and the Available Redemptions count is increased by 1. You can identify vouchers in three ways: - By **id**: Provide the voucher ID - By **code** and **customer_id**: Provide both the voucher code and customer ID **Tier 3 (Low)** — See rate limit table operationId: RollbackAListOfVouchers security: - httpBasic: [] - api_key: [] parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/Rollbackalistofvouchersrequest' - example: vouchers: - id: 538294 - id: 538295 examples: option1: summary: Rollback by ID description: Rollback vouchers using their IDs value: vouchers: - id: 538294 - id: 538295 option2: summary: Rollback by code and customer_id description: Rollback vouchers using code and customer_id value: vouchers: - customer_id: 1 code: CODE1 - customer_id: 2 code: CODE2 required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: >- When any of the parameters is not valid or missing, or when the voucher cannot be rolled back. This can happen when: - The request body is invalid or missing required fields - The voucher is not in redeemed status (only redeemed vouchers can be rolled back) - The voucher has expired (voucher_expired) - The voucher availability date is later than the current date (voucher_out_date) - Other validation errors headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: >- When any of the parameters is not valid or missing, or when the voucher cannot be rolled back. Possible error codes: - invalid_request: When the request body is invalid or missing required fields - invalid_request: When the voucher is not in redeemed status (error message: "voucher with {id/code} is not in redeemed status") - invalid_request: When the voucher has expired (error message: "error voucher expired", code in voucher: voucher_expired) - invalid_request: When the voucher availability date is later than the current date (error message: "the vouchers availability date is superior to the current date", code in voucher: voucher_out_date) example: error: voucher with id 538294 is not in redeemed status code: invalid_request examples: invalid_request: summary: Invalid request parameters value: error: error message code: invalid_request voucher_not_redeemed: summary: Voucher not in redeemed status value: error: voucher with id 538294 is not in redeemed status code: invalid_request voucher_expired: summary: Voucher expired value: error: error voucher expired code: invalid_request voucher_out_date: summary: Voucher out of date value: error: >- the vouchers availability date is superior to the current date code: invalid_request '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: >- Voucher not found, customer not found or voucher does not belong to the customer. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Vouchervalidationresponse1' - description: >- Voucher not found, customer not found or voucher does not belong to the customer. example: code: voucher_not_found error: >- Voucher not found, customer not found or voucher does not belong to the customer. example: code: voucher_not_found error: >- Voucher not found, customer not found or voucher does not belong to the customer. '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/print: post: tags: - campaign vouchers summary: Print a list of vouchers description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration.Get an array of vouchers ( or messages ) in order to print them on your POS activity. Please be aware that the list of vouchers will be sorted regarding the following elements: 1. Campaign priority (if any): This is because some type of campaigns have priority over others. 2. Voucher priority (if any): This is precisely to control which vouchers should be printed first in case a given campaign has several. 3. Voucher availability (always): The list of vouchers will start with the first that will expire on top. By default this request marks the vouchers as "printed" so won't get the same vouchers again in the next call ( for testing purposes: you can avoid this behaviour with a debug param ). All vouchers printed are valid an ready to redeem. When a voucher has a product allocation related to an internal category, by default the POS does receive the product IDs (*product_ids*) belonging to that internal category. For the POS to also receive the external product category, it must be configured in the company configuration. Additionally, 'purchased_product_ids' will provide information about the purchased products in relation to a specific campaign. Example of how you should print vouchers: link **Tier 3 (Low)** — See rate limit table operationId: PrintsAListOfVouchers parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/Printsalistofvouchersrequest' - example: customer_id: 345 size: 3 exclude_codes: - '3412876123876' - '123981928798712' location_id: 1 activity_id: 100005677 debug: false example: customer_id: 345 size: 3 exclude_codes: - '3412876123876' - '123981928798712' location_id: 1 activity_id: 100005677 debug: false required: true responses: '200': description: >- We encourage to transform the code to a barcode, use the name as the title of the coupon and available_from and available_to as information. headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Printsalistofvouchersresponse' description: >- We encourage to transform the code to a barcode, use the name as the title of the coupon and available_from and available_to as information. example: - code: '123123123987987987' available_from: '2016-02-10' available_to: '2016-02-28' name: Discount meat 50% description: Discount meat 50% extended description image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png key: dis50meat available_redemptions: 1 location_ids: - 1 - 2 max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 has_points: true affectation: activity features: - id: 1234 taxonomy_slug: a_slug payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash - code: '1123987123987123' available_from: '2016-03-10' available_to: '2016-03-20' name: Discount dairy products 50% description: Discount meat 50% extended description image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png key: dis50dairy available_redemptions: 1 location_ids: - 1 - 2 purchased_product_ids: - 123 - 124 max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 has_points: true affectation: activity features: - id: 1234 taxonomy_slug: a_slug payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash - code: '123987123981723' available_from: '2016-01-01' available_to: '2016-06-01' name: Discount fish 50% description: Discount meat 50% extended description image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png key: dis50fish available_redemptions: 1 location_ids: - 1 - 2 purchased_product_ids: - 123 - 124 max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 has_points: true affectation: activity features: - id: 1234 taxonomy_slug: a_slug payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash example: - code: '123123123987987987' available_from: '2016-02-10' available_to: '2016-02-28' name: Discount meat 50% description: Discount meat 50% extended description image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png key: dis50meat available_redemptions: 1 location_ids: - 1 - 2 purchased_product_ids: - 123 - 124 max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 has_points: true affectation: activity features: - id: 1234 taxonomy_slug: a_slug payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash - code: '1123987123987123' available_from: '2016-03-10' available_to: '2016-03-20' name: Discount dairy products 50% description: Discount meat 50% extended description image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png key: dis50dairy available_redemptions: 1 location_ids: - 1 - 2 purchased_product_ids: - 123 - 124 max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 has_points: true affectation: activity features: - id: 1234 taxonomy_slug: a_slug payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash - code: '123987123981723' available_from: '2016-01-01' available_to: '2016-06-01' name: Discount fish 50% description: Discount meat 50% extended description image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png key: dis50fish available_redemptions: 1 location_ids: - 1 - 2 purchased_product_ids: - 123 - 124 max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 has_points: true affectation: activity features: - id: 1234 taxonomy_slug: a_slug payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code examples: account_not_verified: value: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false put: tags: - campaign vouchers summary: Print a list of specified vouchers description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration. Sets the status of the specified vouchers to 'printed'. **Tier 3 (Low)** — See rate limit table operationId: UpdateAListOfVouchersToPrintedState parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: >- #/components/schemas/Updatealistofvoucherstoprintedstaterequest - example: activity_id: 238 vouchers: - code: '1234' example: activity_id: 238 vouchers: - code: '1234' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: >- When the `vouchers` array size is bigger than 50 or any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: >- When the `vouchers` array size is bigger than 50 or any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code examples: account_not_verified: value: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/{code}/select: post: tags: - campaign vouchers summary: Select a Voucher description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration.Sets the specified voucher as 'selected'. A voucher will be selected by the customer in order to be used in the next purchase. **Tier 3 (Low)** — See rate limit table operationId: VoucherSelection parameters: - name: code in: path description: Code of the voucher. required: true style: simple schema: type: string example: '27454637261254' responses: '200': description: '- When the voucher is valid and has been selected.' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherselectionresponse' - description: '- When the voucher is valid and has been selected.' example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: true available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash has_points: false affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: true available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash has_points: false affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash '403': description: Customer account is not active headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '404': description: Voucher not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherselectionresponse1' - description: Voucher not found example: code: voucher_not_found error: error get voucher {code} on company {company} example: code: voucher_not_found error: error get voucher {code} on company {company} '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/{code}/deselect: post: tags: - campaign vouchers summary: Deselect a Voucher description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration.Sets the specified voucher as not selected. **Tier 3 (Low)** — See rate limit table operationId: VoucherDeselection parameters: - name: code in: path description: Code of the voucher. required: true style: simple schema: type: string example: '27454637261254' responses: '200': description: '- When the voucher is valid and has been deselected.' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherdeselectionresponse' - description: '- When the voucher is valid and has been deselected.' example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: false available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash has_points: false affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: false available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash has_points: false affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash '403': description: Customer account is not active headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '404': description: Voucher not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherdeselectionresponse1' - description: Voucher not found example: code: voucher_not_found error: error get voucher {code} on company {company} example: code: voucher_not_found error: error get voucher {code} on company {company} '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/select: put: tags: - campaign vouchers summary: Select a list of Vouchers description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration. Sets the status of the specified vouchers to 'selected'. This feature is helpful to implement vouchers that are automatically redeemed in the next purchase. **Tier 3 (Low)** — See rate limit table operationId: UpdateAListOfVouchersToSelectedState security: - httpBasic: [] - api_key: [] parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: >- #/components/schemas/Updatealistofvoucherstoselectedstaterequest - example: vouchers: - code: '1234' - code: '4567' example: vouchers: - code: '1234' - code: '4567' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: >- When the `vouchers` array size is bigger than 50 or any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: >- When the `vouchers` array size is bigger than 50 or any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code examples: account_not_verified: value: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '404': description: Voucher not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherfreezeresponse1' - description: Voucher not found example: code: voucher_not_found error: error get voucher {code} on company {company} example: code: voucher_not_found error: error get voucher {code} on company {company} '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/deselect: put: tags: - campaign vouchers summary: Deselect a list of Vouchers description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration. Sets the status of the specified vouchers to deselected `"selected": false`. This feature is helpful to implement vouchers that are automatically redeemed in the next purchase. **Tier 3 (Low)** — See rate limit table operationId: UpdateAListOfVouchersToDeselectedState security: - httpBasic: [] - api_key: [] parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: >- #/components/schemas/Updatealistofvoucherstoselectedstaterequest - example: vouchers: - code: '1234' - code: '4567' example: vouchers: - code: '1234' - code: '4567' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: >- When the `vouchers` array size is bigger than 50 or any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: >- When the `vouchers` array size is bigger than 50 or any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code examples: account_not_verified: value: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '404': description: Voucher not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherdeselectionresponse1' - description: Voucher not found example: code: voucher_not_found error: error get voucher {code} on company {company} example: code: voucher_not_found error: error get voucher {code} on company {company} '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/{code}/freeze: post: tags: - campaign vouchers summary: Freeze a Voucher description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration.Sets the specified voucher as frozen. A frozen voucher is not printed nor redeemable. **Tier 3 (Low)** — See rate limit table operationId: VoucherFreeze parameters: - name: code in: path description: Code of the voucher. required: true style: simple schema: type: string example: '27454637261254' responses: '200': description: '- When the voucher is valid and has been frozen.' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherfreezeresponse' - description: '- When the voucher is valid and has been frozen.' example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: true available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash has_points: false affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: true available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash has_points: false affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash '403': description: Customer account is not active headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '404': description: Voucher not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherfreezeresponse1' - description: Voucher not found example: code: voucher_not_found error: error get voucher {code} on company {company} example: code: voucher_not_found error: error get voucher {code} on company {company} '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/{code}/unfreeze: post: tags: - campaign vouchers summary: Unfreeze a Voucher description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration.Sets the specified voucher as unfreezed. **Tier 3 (Low)** — See rate limit table operationId: VoucherRunFreeze parameters: - name: code in: path description: Code of the voucher. required: true style: simple schema: type: string example: '27454637261254' responses: '200': description: '- When the voucher is valid and has been unfrozen.' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherunfreezeresponse' - description: '- When the voucher is valid and has been unfrozen.' example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: false available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 has_points: true affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: false available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash has_points: false affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash '403': description: Customer account is not active headers: {} content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The customer with ID 12345 cannot perform this action because their account is not active (current status: inactive) code: ACCOUNT_NOT_VERIFIED '404': description: Voucher not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Voucherunfreezeresponse1' - description: Voucher not found example: code: voucher_not_found error: error get voucher {code} on company {company} example: code: voucher_not_found error: error get voucher {code} on company {company} '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /vouchers/excluded_products: get: tags: - campaign vouchers summary: Exclude product and product categories description: >- Vouchers represent the association between a coupon and a customer. In some cases your company may be creating the vouchers and in some other cases your company never will create a voucher. It dependes on the level of integration. Get the list of ids of the excluded product and product categories for vouchers at company level. **Tier 3 (Low)** — See rate limit table operationId: GetExcludedProductsForVouchers security: - httpBasic: [] - api_key: [] parameters: [] responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/GetVouchersExcludedProductsResponse' '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /products: post: tags: - products summary: Create a New Product description: '**Tier 3 (Low)** — See rate limit table' operationId: CreateANewProduct parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewProductrequest' - example: id: 1234 name: Chicken breast description: Free run chicken breast code: 1234a margin: 0.11 price: 11.99 cost: 10.23 tax: 0.21 measurement_unit: g status: active custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 2 taxonomy_slug: family example: id: 1234 name: Chicken breast description: Free run chicken breast code: 1234a margin: 0.11 price: 11.99 cost: 10.23 tax: 0.21 measurement_unit: g status: active custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 2 taxonomy_slug: family required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewProductresponse' - example: id: 1234 name: Chicken description: Free run chicken code: p-1code price: 11.99 margin: 0.11 cost: 10.23 tax: 0.21 status: active measurement_unit: g custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: meat - id: 2 taxonomy_slug: fresh example: id: 1234 name: Chicken description: Free run chicken code: p-1code price: 11.99 margin: 0.11 cost: 10.23 tax: 0.21 status: active measurement_unit: g custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: meat - id: 2 taxonomy_slug: fresh '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /products/{id}: get: tags: - products summary: Get product description: '**Tier 3 (Low)** — See rate limit table' operationId: GetProduct parameters: - name: id in: path description: ID of the product. required: true style: simple schema: type: integer format: int64 example: 1234 responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getproductresponse' - example: id: 1234 name: Chicken description: Free run chicken code: p-1code price: 11.99 margin: 0.11 cost: 10.23 tax: 0.21 status: active measurement_unit: g custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 code: 1_abc taxonomy_slug: meat - id: 2 code: 2_def taxonomy_slug: fresh example: id: 1234 name: Chicken description: Free run chicken code: p-1code price: 11.99 margin: 0.11 cost: 10.23 tax: 0.21 status: active measurement_unit: g custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 code: 1_abc taxonomy_slug: meat - id: 2 code: 2_def taxonomy_slug: fresh '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the product is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the product is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false patch: tags: - products summary: Update a Product description: '**Tier 3 (Low)** — See rate limit table' operationId: UpdateAproduct parameters: - name: id in: path description: Id of the product required: true style: simple schema: type: integer format: int64 example: 1234 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaProductrequest' - example: name: Chicken breast description: Free run chicken breast code: 1234a margin: 0.11 price: 11.99 cost: 10.23 tax: 0.21 measurement_unit: g status: active custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 2 taxonomy_slug: family example: name: Chicken breast description: Free run chicken breast code: 1234a margin: 0.11 price: 11.99 cost: 10.23 tax: 0.21 measurement_unit: g status: active custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 2 taxonomy_slug: family required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaProductresponse' - example: id: 1234 name: Chicken description: Free run chicken code: p-1code price: 11.99 margin: 0.11 cost: 10.23 tax: 0.21 status: active measurement_unit: g custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: meat - id: 2 taxonomy_slug: fresh example: id: 1234 name: Chicken description: Free run chicken code: p-1code price: 11.99 margin: 0.11 cost: 10.23 tax: 0.21 status: active measurement_unit: g custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: meat - id: 2 taxonomy_slug: fresh '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: When the product is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the product is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - products summary: Delete a Product description: '**Tier 3 (Low)** — See rate limit table' operationId: DeleteAProduct parameters: - name: id in: path description: ID of the product required: true style: simple schema: type: integer format: int64 example: 1234 - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: When the product is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the product is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /taxonomies: post: tags: - product taxonomies summary: Create a product taxonomy description: >- Manage the main different set of groups that you'll need to classify your products. **Tier 3 (Low)** — See rate limit table operationId: CreateANewTaxonomy parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewTaxonomyrequest' - example: name: Meat slug: meat example: name: Meat slug: meat required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /taxonomies/{slug}: patch: tags: - product taxonomies summary: Update a product taxonomy description: >- Manage the main different set of groups that you'll need to classify your products. **Tier 3 (Low)** — See rate limit table operationId: UpdateATaxonomy parameters: - name: slug in: path description: Slug of the taxonomy required: true style: simple schema: type: string example: meat requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaTaxonomyrequest' - example: name: Dairy Products example: name: Dairy Products required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: When the taxonomy is not found. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the taxonomy is not found. example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - product taxonomies summary: Delete a product taxonomy description: >- Manage the main different set of groups that you'll need to classify your products. **Tier 3 (Low)** — See rate limit table operationId: DeleteATaxonomy parameters: - name: slug in: path description: Slug of the taxonomy required: true style: simple schema: type: string example: dairy_products - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: When the taxonomy is not found. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the taxonomy is not found. example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /taxonomies/{taxonomy_slug}/features: post: tags: - product features summary: Create a product feature description: >- Manage the different values in which a product will be categorized under a certain taxonomy. Remember that everytime that you create a new feature you'll have to update every product belonging to this new feature. **Tier 3 (Low)** — See rate limit table operationId: CreateANewFeature parameters: - name: taxonomy_slug in: path description: Slug of the taxonomy required: true style: simple schema: type: string example: family requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewFeaturerequest' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: When the taxonomy is not found. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the taxonomy is not found. example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /taxonomies/{taxonomy_slug}/features/{id}: patch: tags: - product features summary: Update a product feature description: >- Manage the different values in which a product will be categorized under a certain taxonomy. Remember that everytime that you create a new feature you'll have to update every product belonging to this new feature. **Tier 3 (Low)** — See rate limit table operationId: UpdateAFeature parameters: - name: taxonomy_slug in: path description: Slug of the taxonomy required: true style: simple schema: type: string example: family - name: id in: path description: Identifier of the feature required: true style: simple schema: type: string example: 1234 - name: search_param in: query description: >- The property to find the feature by. It can be either `id` or `code`. Example: `/taxonomies/family/features/1234?search_param=code` It is not included in the request, it will take the default value `id`. If `search_param=code` is used, the request body must contain the code in the `parent_features` array. required: false style: simple schema: type: string enum: - id - code example: code requestBody: description: '' content: application/json: schema: oneOf: - $ref: '#/components/schemas/UpdateaFeaturerequestById' - $ref: '#/components/schemas/UpdateaFeaturerequestByCode' required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: When the feature is not found. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the feature is not found. example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - product features summary: Delete a product feature description: >- Manage the different values in which a product will be categorized under a certain taxonomy. Remember that everytime that you create a new feature you'll have to update every product belonging to this new feature. **Tier 3 (Low)** — See rate limit table operationId: DeleteAFeature parameters: - name: taxonomy_slug in: path description: Slug of the taxonomy required: true style: simple schema: type: string example: family - name: id in: path description: Identifier of the feature required: true style: simple schema: type: string example: 1234 - name: search_param in: query description: >- The property to find the feature by. It can be either 'id' or 'code'. It is not included in the request, it will take the default value 'id'. required: false style: simple schema: type: string enum: - id - code example: code - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: When the feature is not found. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the feature is not found. example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /locations: post: tags: - locations summary: Create a New Location description: >- - `id`, `code` can´t be sent at the same time. Just one of them is allowed. **Tier 3 (Low)** — See rate limit table operationId: CreateANewLocation parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewLocationrequest' - example: id: 1234 name: Local number 1234 postal_code: '08110' address: Joan Miró address_extra: '31' phone: '678513344' country: ES currency: EUR city: Barcelona state: Catalonia email: local1234@google.es longitude: 40.68906 latitude: 74.044636 status: active score_exchange_id: 12 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 2 taxonomy_slug: family example: id: 1234 name: Local number 1234 postal_code: '08110' address: Joan Miró address_extra: '31' phone: '678513344' country: ES currency: EUR city: Barcelona state: Catalonia email: local1234@google.es longitude: 40.68906 latitude: 74.044636 status: active score_exchange_id: 12 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 2 taxonomy_slug: family required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewLocationresponse' - example: id: 1234 name: Local location postal_code: '08080' address: Joan Tshu address_extra: N1 phone: '638849999' country: ES currency: EUR city: Madrid state: Madrid email: local1234@test.test longitude: 41.62366 latitude: 71.0262336 status: active score_exchange_id: 15 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: test1 - id: 2 taxonomy_slug: test2 example: id: 1234 name: Local location postal_code: '08080' address: Joan Tshu address_extra: N1 phone: '638849999' country: ES currency: EUR city: Madrid state: Madrid email: local1234@test.test longitude: 41.62366 latitude: 71.0262336 status: active score_exchange_id: 15 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: test1 - id: 2 taxonomy_slug: test2 '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /locations/{value}: get: tags: - locations summary: Get a location description: '**Tier 3 (Low)** — See rate limit table' operationId: GetLocation parameters: - name: value in: path description: >- Could be an integer or a string. - It must be an integer when `search_param` = id or `search_param` is not provided. The system will search the location by its **id**. - It is treated as string when `search_param` = code. The system will search the location by its **code**. required: true style: simple schema: type: string example: 1234,53345345B - name: search_param in: query description: The param field used for the location search. schema: type: string enum: - id - code example: id responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getlocationresponse' - example: id: 1234 code: 53345345B name: Local location postal_code: '08080' address: Joan Tshu address_extra: N1 phone: '638849999' country: ES currency: EUR city: Madrid state: Madrid email: local1234@test.test longitude: 41.62366 latitude: 71.0262336 status: active score_exchange_id: 15 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: test1 - id: 2 taxonomy_slug: test2 example: id: 1234 code: 53345345B name: Local location postal_code: '08080' address: Joan Tshu address_extra: N1 phone: '638849999' country: ES currency: EUR city: Madrid state: Madrid email: local1234@test.test longitude: 41.62366 latitude: 71.0262336 status: active score_exchange_id: 15 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: test1 - id: 2 taxonomy_slug: test2 '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '404': description: When the location is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the location is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false patch: tags: - locations summary: Update a Location description: '**Tier 3 (Low)** — See rate limit table' operationId: UpdateALocation parameters: - name: value in: path description: >- Could be an integer or a string. - It must be an integer when `search_param` = id or `search_param` is not provided. The system will search the location by its **id**. - It is treated as string when `search_param` = code. The system will search the location by its **code**. required: true style: simple schema: type: string example: 1234,53345345B - name: search_param in: query description: The param field used for the location search. schema: type: string enum: - id - code example: id requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaLocationrequest' - example: name: Local number 1234 postal_code: '08110' address: Joan Miró address_extra: '31' phone: '678513344' country: ES currency: EUR city: Barcelona state: Catalonia email: local1234@google.es longitude: 40.68906 latitude: 74.044636 status: active score_exchange_id: 12 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 2 taxonomy_slug: family example: name: Local number 1234 postal_code: '08110' address: Joan Miró address_extra: '31' phone: '678513344' country: ES currency: EUR city: Barcelona state: Catalonia email: local1234@google.es longitude: 40.68906 latitude: 74.044636 status: active score_exchange_id: 12 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 2 taxonomy_slug: family required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaLocationresponse' - example: id: 1234 code: 53345345B name: Local location postal_code: '08080' address: Joan Tshu address_extra: N1 phone: '638849999' country: ES currency: EUR city: Madrid state: Madrid email: local1234@test.test longitude: 41.62366 latitude: 71.0262336 status: active score_exchange_id: 15 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: test1 - id: 2 taxonomy_slug: test2 example: id: 1234 code: 53345345B name: Local location postal_code: '08080' address: Joan Tshu address_extra: N1 phone: '638849999' country: ES currency: EUR city: Madrid state: Madrid email: local1234@test.test longitude: 41.62366 latitude: 71.0262336 status: active score_exchange_id: 15 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: test1 - id: 2 taxonomy_slug: test2 '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - locations summary: Delete a Location description: '**Tier 3 (Low)** — See rate limit table' operationId: DeleteALocation parameters: - name: value in: path description: >- Could be an integer or a string. - It must be an integer when `search_param` = id or `search_param` is not provided. The system will search the location by its **id**. - It is treated as string when `search_param` = code. The system will search the location by its **code**. required: true style: simple schema: type: string example: 1234,53345345B - name: search_param in: query description: The param field used for the location search. schema: type: string enum: - id - code example: id - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/DeleteaLocationresponse' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /locations/taxonomies: post: tags: - location taxonomies summary: Create a New Location Taxonomy description: >- Manage the main different set of groups that you'll need to classify your locations. **Tier 3 (Low)** — See rate limit table operationId: CreateANewLocationTaxonomy parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewLocationTaxonomyrequest' - example: name: Meat slug: meat_pub|1 example: name: Meat slug: meat_pub|1 required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewLocationTaxonomyresponse' - example: id: 1 name: Meat slug: meat_pub|1 origin: external example: id: 1 name: Meat slug: meat_pub|1 origin: external '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /locations/taxonomies/{slug}: patch: tags: - location taxonomies summary: Update a Location Taxonomy description: >- Manage the main different set of groups that you'll need to classify your locations. **Tier 3 (Low)** — See rate limit table operationId: UpdateALocationTaxonomy parameters: - name: slug in: path description: Slug of the taxonomy required: true style: simple schema: type: string example: meat_pub|1 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaLocationTaxonomyrequest' - example: name: Most visited example: name: Most visited required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaLocationTaxonomyresponse' - example: status: success example: status: success '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: Location Taxonomy slug is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Location Taxonomy slug is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - location taxonomies summary: Delete a Location Taxonomy description: >- Manage the main different set of groups that you'll need to classify your locations.When a location taxonomy is deleted, the categories associated to it are deleted as well. **Tier 3 (Low)** — See rate limit table operationId: DeleteALocationTaxonomy parameters: - name: slug in: path description: Slug of the taxonomy required: true style: simple schema: type: string example: meat_pub|1 - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/DeleteaLocationTaxonomyresponse' - example: status: success example: status: success '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: Location Taxonomy slug is not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Location Taxonomy slug is not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /locations/taxonomies/{taxonomy_slug}/features: post: tags: - location features summary: Create a New Location Feature description: |- Manage the features used to classify your locations. **Tier 3 (Low)** — See rate limit table operationId: CreateALocationFeature parameters: - name: taxonomy_slug in: path description: Slug of the taxonomy the feature belongs to. required: true style: simple schema: type: string example: region requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaLocationFeaturerequest' - example: id: 1 name: Barcelona example: id: 1 name: Barcelona required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaLocationFeatureresponse' - example: external_id: 1 id: 1323542 name: Barcelona slug: region|1 taxonomy_slug: region example: external_id: 1 id: 1323542 name: Barcelona slug: region|1 taxonomy_slug: region '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /locations/taxonomies/{taxonomy_slug}/features/{id}: patch: tags: - location features summary: Update a Location Feature description: |- Manage the features used to classify your locations. **Tier 3 (Low)** — See rate limit table operationId: UpdateALocationFeature parameters: - name: taxonomy_slug in: path description: Slug of the taxonomy the feature belongs to. required: true style: simple schema: type: string example: region - name: id in: path description: Unique identifier of the feature within its taxonomy. required: true style: simple schema: type: integer format: int64 example: 1 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaLocationFeaturerequest' - example: name: BCN example: name: BCN required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaLocationFeatureresponse' - example: external_id: 1 id: 1323542 name: BCN slug: region|1 taxonomy_slug: region example: external_id: 1 id: 1323542 name: BCN slug: region|1 taxonomy_slug: region '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: Location Feature not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Location Feature not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - location features summary: Delete a Location Feature description: |- Manage the features used to classify your locations. **Tier 3 (Low)** — See rate limit table operationId: DeleteALocationFeature parameters: - name: taxonomy_slug in: path description: Slug of the taxonomy the feature belongs to. required: true style: simple schema: type: string example: region - name: id in: path description: Unique identifier of the feature within its taxonomy. required: true style: simple schema: type: integer format: int64 example: 1 - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/DeleteaLocationFeatureresponse' - example: status: success example: status: success '400': description: When any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '404': description: Location Feature not found headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Location Feature not found example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /promotions: post: tags: - promotions summary: Create a New Promotion description: >- A promotion is defining a generic discount that is applicable based on the products purchased by the customer, its applicable without requiring any action by the client. The big difference between a promotion and a coupon is that a promotion does not require the customer to present a voucher. **Tier 3 (Low)** — See rate limit table operationId: CreateANewPromotion parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateaNewPromotionrequest' - example: id: 1234 name: Promotion 2x1 description: Pay one and get the second one for free available_from: '2016-01-01' available_to: '2016-02-01' active: true discount: 0.33 marketing_cost: 35975.52 created_at: '2016-01-01T12:00:00Z' location_ids: - 1 - 2 product_ids: - 1 - 2 collective_ids: - 1 - 2 collective_slugs: - employees - bigfamily promotional_discount_name: 2x1 cumulative: true min_units: 2 max_units: 5 min_money: 0.5 max_money: 10.5 discount_type: percent affectation: product example: id: 1234 name: Promotion 2x1 description: Pay one and get the second one for free available_from: '2016-01-01' available_to: '2016-02-01' active: true discount: 0.33 marketing_cost: 35975.52 created_at: '2016-01-01T12:00:00Z' location_ids: - 1 - 2 product_ids: - 1 - 2 collective_ids: - 1 - 2 collective_slugs: - employees - bigfamily promotional_discount_name: 2x1 cumulative: true min_units: 2 max_units: 5 min_money: 0.5 max_money: 10.5 discount_type: percent affectation: product required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /promotions/{id}: patch: tags: - promotions summary: Update a Promotion description: >- A promotion is defining a generic discount that is applicable based on the products purchased by the customer, its applicable without requiring any action by the client. The big difference between a promotion and a coupon is that a promotion does not require the customer to present a voucher. **Tier 3 (Low)** — See rate limit table operationId: UpdateAPromotion parameters: - name: id in: path description: ID of the promotion required: true style: simple schema: type: integer format: int64 example: 12 requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateaPromotionrequest' - example: name: Promotion 2x1 description: Pay one and get the second one for free available_from: '2016-01-01' available_to: '2016-02-01' active: true discount: 0.33 marketing_cost: 35975.52 created_at: '2016-01-01T12:00:00Z' updated_at: '2016-01-01T12:00:00Z' location_ids: - 1 - 2 product_ids: - 1 - 2 collective_ids: - '1' - '2' collective_slugs: - employees - bigfamily promotional_discount_name: 2x1 cumulative: true min_units: 2 max_units: 5 min_money: 0.5 max_money: 10.5 discount_type: percent affectation: product example: name: Promotion 2x1 description: Pay one and get the second one for free available_from: '2016-01-01' available_to: '2016-02-01' active: true discount: 0.33 marketing_cost: 35975.52 created_at: '2016-01-01T12:00:00Z' updated_at: '2016-01-01T12:00:00Z' product_ids: - 1 - 2 collective_ids: - '1' - '2' collective_slugs: - employees - bigfamily promotional_discount_name: 2x1 cumulative: true min_units: 2 max_units: 5 min_money: 0.5 max_money: 10.5 discount_type: cash affectation: product featture_location_ids: - 1 - 2 required: true responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - example: status: success example: status: success '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false delete: tags: - promotions summary: Delete a Promotion description: >- A promotion is defining a generic discount that is applicable based on the products purchased by the customer, its applicable without requiring any action by the client. The big difference between a promotion and a coupon is that a promotion does not require the customer to present a voucher. **Tier 3 (Low)** — See rate limit table operationId: DeleteAPromotion parameters: - name: id in: path description: ID of the promotion required: true style: simple schema: type: integer format: int64 example: 12 - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/DeleteaPromotionresponse' - example: status: success example: status: success deprecated: false /check: get: tags: - check summary: Check API availability description: '**Tier 3 (Low)** — See rate limit table' operationId: CheckAPIAvailability parameters: [] responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CheckAPIavailabilityresponse' - example: status: ok example: status: ok deprecated: false /customers/{id}/discount_report: get: summary: Get a discount report description: >- Get a report with information about how much money save the customer related to vouchers, points and promotions annually but classified with months. **Tier 3 (Low)** — See rate limit table operationId: GetADiscountReport parameters: - name: id in: path description: '' required: true style: simple schema: type: string - name: Content-Type in: header description: '' required: true style: simple schema: enum: - application/json type: string example: application/json responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getadiscountreportresponse' - example: data: - month: 1 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 2 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 3 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 4 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 5 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 6 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 7 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 8 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 9 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 10 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 11 year: 2019 discounts: score: 2 voucher: 3 promotion: 4 - month: 12 year: 2019 discounts: score: 5 voucher: 2 promotion: 7 example: data: - month: 1 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 2 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 3 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 4 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 5 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 6 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 7 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 8 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 9 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 10 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 11 year: 2019 discounts: score: 2 voucher: 3 promotion: 4 - month: 12 year: 2019 discounts: score: 5 voucher: 2 promotion: 7 '400': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Getadiscountreportresponse1' - example: code: invalid_request error: error message example: code: invalid_request error: error message '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false /messages/print: post: tags: - messages summary: Prints a list of messages description: >- A message is a notification that you can print in a purchase activity for a certain customer. You'll probably only need to use the Print method.Get an array of messages for a certain customer in order to print them on a purchase activity in your POS. Example of how you should print vouchers: link **Tier 3 (Low)** — See rate limit table operationId: PrintsAListOfMessages parameters: [] requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/Printsalistofmessagesrequest' - example: customer_id: 345 size: 3 location_id: 1 activity_id: 100005677 debug: false available_redemptions: 1 example: customer_id: 345 size: 3 location_id: 1 activity_id: 100005677 debug: false available_redemptions: 1 required: true responses: '200': description: >- We encourage to use the name as the title of the message and the description as the body of the message. You can completely ignore "code", "available_from" and "available_to". You should use only "name" and "descritption" for printing your messages in the purchase activity. headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/Printsalistofmessagesresponse' description: >- We encourage to use the name as the title of the message and the description as the body of the message. You can completely ignore "code", "available_from" and "available_to". You should use only "name" and "descritption" for printing your messages in the purchase activity. example: - code: '123123123987987987' available_from: '2016-02-10' available_to: '2016-02-28' name: Discount meat 50% description: Discount meat 50% extended description - code: '1123987123987123' available_from: '2016-03-10' available_to: '2016-03-20' name: Discount dairy products 50% description: Discount meat 50% extended description - code: '123987123981723' available_from: '2016-01-01' available_to: '2016-06-01' name: Discount fish 50% description: Discount meat 50% extended description example: - code: '123123123987987987' available_from: '2016-02-10' available_to: '2016-02-28' name: Discount meat 50% description: Discount meat 50% extended description - code: '1123987123987123' available_from: '2016-03-10' available_to: '2016-03-20' name: Discount dairy products 50% description: Discount meat 50% extended description - code: '123987123981723' available_from: '2016-01-01' available_to: '2016-06-01' name: Discount fish 50% description: Discount meat 50% extended description '400': description: When the any of the parameters is not valid or missing. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: When the any of the parameters is not valid or missing. example: error: error message code: error code example: error: error message code: error code '403': description: Api key is not valid or missing headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Api key is not valid or missing example: error: error message code: error code example: error: error message code: error code '500': description: Server error, try again and contact with support. headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - description: Server error, try again and contact with support. example: error: error message code: error code example: error: error message code: error code deprecated: false components: securitySchemes: httpBasic: type: http scheme: basic api_key: type: apiKey in: header name: api_key schemas: CustomerListItem: title: CustomerListItem type: object properties: dni: type: string description: >- Identification card number. It must be unique per customer. It will always be saved in uppercase. example: 53023040B name: type: string surname_1: type: string surname_2: type: string email: type: string birth: type: string description: | Date of the birth. In YYYY-MM-DD format. Years outside the range 1900-9999 are automatically set to null. example: '2016-01-01' phone_prefix: type: string description: Phone country prefix. When phone is filled phone_prefix is required. example: '34' status: type: string enum: - active - inactive default: active description: >- Status of the customer, must be one of them: active or inactive. Active is the default value. example: active phone: type: string description: Mobile phone number. example: '678123456' address: type: string address_extra: type: string postal_code: type: string city: type: string description: City of the customer example: Barcelona state: type: string description: State or region of the customer example: Catalonia id: type: string trimestral_expend: type: number format: float default: 0 score_available: type: integer format: int64 default: 0 score: type: integer format: int64 default: 0 paper_free: type: boolean default: false merged: type: boolean preferred_language: type: string registration_location_id: type: integer format: int64 description: Identifier of the store in which the customer was registered. example: 1234 registration_location_code: type: string description: Code of the store in which the customer was registered. example: S22C-Plaza fraudulent: type: boolean description: If the customer is fraudulent or not. example: false collective_id: type: integer format: int64 description: Identifier of the collective_id. example: 123 attributes: type: object description: >- Custom attributes as key-value pairs. Supports flexible data types including strings, numbers, booleans, arrays, and nested objects. Use this field instead of the deprecated custom1-custom11 and custom1f-custom8f fields. example: membership_level: premium points_balance: 1250 example: dni: 12345678A name: Jon surname_1: Snow surname_2: Sand email: jon@example.com birth: '1990-12-31' phone_prefix: '34' status: active phone: '600600600' address: Calle ABC, 10 address_extra: '-' postal_code: '55555' city: Barcelona state: Catalonia id: '123' trimestral_expend: 123 score: 100 score_available: 80 paper_free: true merged: true preferred_language: es registration_location_id: 1234 registration_location_code: S22C-Plaza fraudulent: false collective_id: 123 attributes: membership_level: premium points_balance: 1250 GetAListOfCustomersResponse: title: GetAListOfCustomersResponse type: object properties: list: type: array items: $ref: '#/components/schemas/CustomerListItem' description: Data of a customer in the list example: list: - dni: 12345678A name: Jon surname_1: Snow surname_2: Sand email: jon@example.com birth: '1990-12-31' phone_prefix: '34' status: active phone: '600600600' address: Calle ABC, 10 address_extra: '-' postal_code: '55555' city: Barcelona state: Catalonia id: '123' trimestral_expend: 123 score: 100 score_available: 80 paper_free: true merged: true preferred_language: es registration_location_id: 1234 registration_location_code: S22C-Plaza fraudulent: false collective_id: 123 attributes: membership_level: premium points_balance: 1250 Error: title: Error type: object properties: error: type: string example: error message code: type: string example: error code CreateaNewCustomerrequest: title: CreateaNewCustomerrequest required: - id - name - registration_location_id type: object properties: id: type: integer format: int64 description: >- ID of the customer in form of an integer. It becomes optional if code is present. example: 1234 code: type: string description: >- Alternatibe customer's identification in form of an Alphanumeric. It admits up to 36 characters. example: A54fTr1 card_id: type: integer format: int64 description: >- When creating a unified customer, use this field to indicate the customer's card. example: 1233 name: type: string description: Name. example: Jon surname_1: type: string description: Surname 1. example: Snow surname_2: type: string description: Surname 2. example: Sand email: type: string description: >- Email. It must be unique and it is case insensitive. It will always be saved in lowercase. example: jon@winter.com phone: type: string description: |- Mobile phone number. An extra validation will be checked: - If the phone_prefix is 34 (Spain) the phone must start with 6 or 7 and be 9 digit length. - If the phone_prefix is 376 (Andorra) the phone must start with 3 or 6 and be 6 digit length. example: '678123456' phone_prefix: type: string description: Phone country prefix. When phone is filled phone_prefix is required example: '34' address: type: string description: Address. example: Snow Tree address_extra: type: string description: 2 (optional, string) - Extra information about the address. example: 31 1 city: type: string description: The customer's city. example: Mataró state: type: string description: The city's region. example: Barcelona postal_code: type: string description: Postal code. example: '08110' birth: type: string description: > Date of the birth. Must be in YYYY-MM-DD format. Years must be between 1900 and 9999 (inclusive). Birth dates with years outside this range will be automatically set to null. example: '2016-01-01' gender: type: string description: |- Gender of the customer, must be one of them: masculine feminine example: feminine document_type: type: string description: Type of document that identifies the customer. example: dni dni: type: string description: >- Identification card number. It must be unique per customer. It will always be saved in uppercase. example: 53023040B country: type: string description: >- [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code in capital letters example: ES authentication_token: type: string description: Authentication token example: y78rhr29feuyfw89 registration_location_id: type: integer format: int64 description: >- Registration location id. It becomes optional if registration_location_code is present. example: 123 registration_location_code: type: string description: Registration location code. example: loc_cod_001 usual_location_id: type: integer format: int64 description: >- Usual location id. It could be overriden by automatic calculations from Loyal Guru. example: 123 status: type: string description: |- Status of the customer, must be one of them: active inactive Default: active example: active password: type: string description: >- Password of the customer. If not specified the system will create one. example: mysecretpassword password_confirmation: type: string description: Confirmation password of the customer example: mysecretpassword creation_date: type: string description: >- DateTime of the creation of the customer. The format must be ISO 8601 in UTC, e.g. '2016-01-01T20:23:20Z'. example: '2016-01-01T20:23:20Z' sms_unsubscribe: type: boolean description: Unsubscribe status for sms campaigns example: true email_unsubscribe: type: boolean description: Unsubscribe status for email campaigns example: true push_unsubscribe: type: boolean description: Unsubscribe status for push campaigns example: true paper_free: type: boolean description: Uses digital activity or not example: false collective_id: type: integer format: int64 description: Collective Id example: 17 collective_slug: type: string description: Collective Slug, only use it when the collective id is not used example: employees communications: type: boolean description: Only true when the customer has accepted to receive communications example: true terms: type: boolean description: Only true when the customer has accepted the gdpr terms example: true profiling: type: boolean description: >- Only true when ther customer are allowed to share his data to make profile metrics (appear in segments, impacted by campaigns, etc) example: true terms_accepted_at: type: string description: >- The date when the customer accepts the gdpr terms. Can be set manually example: '2016-01-02T15:04:05Z' profiling_accepted_at: type: string description: >- The date when the customer accepts the profiling. Can be set manually example: '2016-01-02T15:04:05Z' app: type: boolean description: If customer registration is done by any mobile app example: true push_token: type: string description: >- Mobile app token to send notifications. Only used when app param is true. example: cd9fea48-c2c4-ab88-d4ef-db1f7288af92 custom1: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 1 custom2: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 2 custom3: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 3 custom4: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 4 custom5: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 5 custom6: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 6 custom7: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 7 custom8: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 8 custom9: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 9 custom10: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 10 custom11: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 11 custom1f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom2f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom3f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom4f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom5f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom6f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom7f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom8f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 kind: type: string description: Kind of customer example: ecommerce preferred_language: type: string description: >- [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) preferred language for the customer example: es referred_by: type: integer format: int64 description: >- A friend referral is registered in Loyal Guru when a customer account is created with this referrer field, which is the customer ID of the friend's account (which must be an existing ID in the Loyal Guru platform) Once a customer is created using this referred_by field, a referral event (system trigger called refer_a_friend) is triggered and can be used to reward the inviting person and the referring person with points or rewards under different conditions (defined by the created loyalty rule). See the Help Centre (Refer a Friend document) for more information. example: 232233322 fraudulent: type: boolean description: If the customer is fraudulent or not example: false third_party_consent: type: boolean description: >- This flag indicates whether the customer has accepted the third party data sharing. example: true attributes: type: object description: >- Attributes allow you to store additional data on customers. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) **Unknown Properties:** Properties not defined in the schema are silently discarded - they won't cause validation errors but will NOT be stored. **Case Sensitivity:** Property names are **case-sensitive** per JSON Schema specification. If your schema defines `ClientId`, sending `CLIENTID` or `clientid` will be treated as unknown properties and silently discarded. Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "loyalty_tier": "gold", "customer_score": 850, "newsletter_opt_in": true, "tags": ["vip", "premium", "early_adopter"], "preferred_store_ids": [101, 205, 308], "interests": ["electronics", "fashion", "sports"] } ``` example: loyalty_tier: gold customer_score: 850 newsletter_opt_in: true tags: - vip - premium - early_adopter preferred_store_ids: - 101 - 205 - 308 interests: - electronics - fashion - sports Success: title: Success type: object properties: status: type: string example: success Searchcustomersrequest: title: Search type: object properties: id: type: integer format: int64 description: Customer ID, exclusive with other search params. example: 33 code: type: string description: Customer Code, exclusive with other search params. example: code33 dni: type: string description: Customer DNI, exclusive with other search params. example: 00000000T associate_id: type: integer format: int64 description: Customer Associate ID, exclusive with other search params. example: 34 email: type: string description: Customer Email, exclusive with other search params example: mail@loyal.guru Getcustomerresponse: title: Getcustomerresponse type: object properties: id: type: string code: type: string name: type: string surname_1: type: string surname_2: type: string email: type: string phone: type: string description: |- Mobile phone number. An extra validation will be checked: - If the phone_prefix is 34 (Spain) the phone must start with 6 or 7 and be 9 digit length. - If the phone_prefix is 376 (Andorra) the phone must start with 3 or 6 and be 6 digit length. example: '678123456' phone_prefix: type: string description: Phone country prefix. When phone is filled phone_prefix is required example: '34' address: type: string address_extra: type: string postal_code: type: string city: type: string description: City of the customer example: Barcelona state: type: string description: State or region of the customer example: Catalonia trimestral_expend: type: number format: float score: type: integer format: int64 score_available: type: integer format: int64 paper_free: type: boolean merged: type: boolean merged_to: type: integer format: int64 birth: type: string description: | Date of the birth. In YYYY-MM-DD format. Years outside the range 1900-9999 are automatically set to null. example: '2016-01-01' dni: type: string description: >- Identification card number. It must be unique per customer. It will always be saved in uppercase. example: 53023040B kind: type: string preferred_language: type: string communications: type: boolean app: type: boolean custom1: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 1 custom2: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 2 custom3: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 3 custom4: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 4 custom5: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 5 custom6: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 6 custom7: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 7 custom8: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 8 custom9: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 9 custom10: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 10 custom11: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 11 custom1f: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 1f custom2f: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 2f custom3f: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 3f custom4f: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 4f custom5f: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 5f custom6f: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 6f custom7f: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 7f custom8f: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 8f status: type: string description: |- Status of the customer, must be one of them: active inactive Default: active example: active registration_location_id: type: integer format: int64 description: Identifier of the store in which the customer was registered example: 1234 registration_location_code: type: string description: Code of the store in which the customer was registered example: S22C-Plaza fraudulent: type: boolean description: If the customer is fraudulent or not example: false collective_id: type: integer format: int64 description: Identifier of the collective_id example: 123 third_party_consent: type: boolean description: >- This flag indicates whether the customer has accepted the third party data sharing example: true attributes: type: object description: >- Custom attributes as key-value pairs. Supports flexible data types including strings, numbers, booleans, arrays, and nested objects. Use this field instead of the deprecated custom1-custom11 and custom1f-custom8f fields. example: loyalty_tier: gold customer_score: 850 vip_status: true example: id: '123' code: A54fTr1 name: Jon surname_1: Snow surname_2: Sand email: jon@example.com trimestral_expend: 123 score: 100 score_available: 80 paper_free: true merged: true merged_to: 321 kind: ecommerce preferred_language: es communications: true app: false dni: 12345678Z birth: '1990-12-31' custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom8: custom 8 value custom9: custom 9 value custom10: custom 10 value custom11: custom 11 value custom1f: custom 1f value custom2f: custom 2f value custom3f: custom 3f value custom4f: custom 4f value custom5f: custom 5f value custom6f: custom 6f value custom7f: custom 7f value custom8f: custom 8f value phone: '600600600' phone_prefix: '+34' address: Calle ABC, 10 address_extra: '-' postal_code: '55555' city: Barcelona state: Catalonia status: active registration_location_id: 1234 registration_location_code: S22C-Plaza fraudulent: false collective_id: 123 third_party_consent: true attributes: loyalty_tier: gold customer_score: 850 vip_status: true Deleteacustomerresponse: title: Deleteacustomerresponse required: - status type: object properties: status: type: string example: status: success Deleteacustomerresponse1: title: Deleteacustomerresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: invalid_request error: Error message NumericError: title: NumericError type: object properties: error: type: string description: Human-readable error message example: Customer cannot be deleted while in merging state. code: type: integer description: Numeric error code for programmatic handling example: 63000 company: type: string description: Company slug where the error occurred example: public required: - error - code UpdateaCustomerrequest: title: UpdateaCustomerrequest type: object properties: name: type: string description: Name. example: Jon surname_1: type: string description: Surname 1. example: Snow surname_2: type: string description: Surname 2. example: Sand email: type: string description: >- Email. It must be unique and it is case insensitive. It will always be saved in lowercase. example: jon@winter.com phone: type: string description: |- Mobile phone number. An extra validation will be checked: - If the phone_prefix is 34 (Spain) the phone must start with 6 or 7 and be 9 digit length. - If the phone_prefix is 376 (Andorra) the phone must start with 3 or 6 and be 6 digit length. example: '678123456' phone_prefix: type: string description: Phone country prefix. When phone is filled phone_prefix is required. example: '34' address: type: string description: Address. example: Snow Tree address_extra: type: string description: 2 (optional, string) - Extra information about the address. example: 31 1 city: type: string description: The customer's city. example: Mataró state: type: string description: The city's region. example: Barcelona postal_code: type: string description: Postal code. example: '08110' birth: type: string description: > Date of the birth. Must be in YYYY-MM-DD format. Years must be between 1900 and 9999 (inclusive). Birth dates with years outside this range will be automatically set to null. example: '2016-01-01' gender: type: string description: |- Gender of the customer, must be one of them: masculine feminine example: feminine document_type: type: string description: Type of document that identifies the customer. example: dni dni: type: string description: Identification card number. It will always be saved in uppercase. example: 53023040B country: type: string description: >- [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code in capital letters example: ES authentication_token: type: string description: Authentication token example: y78rhr29feuyfw89 registration_location_id: type: integer format: int64 description: Registration location id. example: 123 registration_location_code: type: string description: Registration location code. example: abc usual_location_id: type: integer format: int64 description: >- Usual location id. It could be overriden by automatic calculations from Loyal Guru. example: 123 status: type: string description: |- Status of the customer, must be one of them: active inactive Default: active example: active creation_date: type: string description: >- DateTime of the creation of the customer. The format must be ISO 8601 in UTC, e.g. '2016-01-01T20:23:20Z'. example: '2016-01-01T20:23:20Z' sms_unsubscribe: type: boolean description: Unsubscribe status for sms campaigns example: true email_unsubscribe: type: boolean description: Unsubscribe status for email campaigns example: true push_unsubscribe: type: boolean description: Unsubscribe status for push campaigns example: true paper_free: type: boolean description: Uses digital activity or not example: false collective_id: type: integer format: int64 description: Collective Id example: 17 collective_slug: type: string description: Collective Slug, only use it,when the collective id is not used example: employees communications: type: boolean description: Only true when the customer has accepted to receive communications example: true terms: type: boolean description: Only true when the customer has accepted the gdpr terms example: true profiling: type: boolean description: >- Only true when ther customer are allowed to share his data to make profile metrics (appear in segments, impacted by campaigns, etc) example: true terms_accepted_at: type: string description: >- The date when the customer accepts the gdpr terms. Can be set manually example: '2016-01-02T15:04:05Z' profiling_accepted_at: type: string description: >- The date when the customer accepts the profiling. Can be set manually example: '2016-01-02T15:04:05Z' app: type: boolean description: If customer registration is done by any mobile app example: false push_token: type: string description: >- Mobile app token to send notifications. Only used when app param is missing, null or true. example: cd9fea48-c2c4-ab88-d4ef-db1f7288af92 custom1: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 1 custom2: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 2 custom3: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 3 custom4: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 4 custom5: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 5 custom6: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 6 custom7: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 7 custom8: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 8 custom9: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 9 custom10: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 10 custom11: type: string deprecated: true description: |- **Use `attributes` instead** Custom value example: custom value 11 custom1f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom2f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom3f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom4f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom5f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom6f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom7f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 custom8f: type: number format: double deprecated: true description: |- **Use `attributes` instead** Numeric custom value example: 10.12 kind: type: string description: Kind of customer example: ecommerce preferred_language: type: string description: >- [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) preferred language for the customer example: es fraudulent: type: boolean description: If the customer is fraudulent or not example: false attributes: type: object description: >- Attributes allow you to store additional data on customers. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Update Behavior (JSON Merge Patch):** - Send only the attributes you want to change - Set a value to `null` to delete that attribute - Omit an attribute to leave it unchanged - Unknown properties (not in schema) are silently discarded **Case Sensitivity:** Property names are **case-sensitive** per JSON Schema specification. If your schema defines `ClientId`, sending `CLIENTID` or `clientid` will be treated as unknown properties and silently discarded. **Validation Timing:** - **Schema validation**: Only the incoming attributes in your request are validated against the schema. Existing attributes are NOT re-validated, allowing schema evolution without breaking updates. - **Count & Size limits**: These apply to the **merged result** (existing + new - deleted). If the total exceeds 50 attributes or 10KB after merging, the request will fail. **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "loyalty_tier": "gold", "customer_score": 850, "newsletter_opt_in": true, "tags": ["vip", "premium", "early_adopter"], "preferred_store_ids": [101, 205, 308], "interests": ["electronics", "fashion", "sports"] } ``` example: loyalty_tier: gold customer_score: 850 newsletter_opt_in: true tags: - vip - premium - early_adopter preferred_store_ids: - 101 - 205 - 308 interests: - electronics - fashion - sports CustomerAttributeList: title: CustomerAttributeList required: - name - value - data_type - attribute_type - slug - system - created_at type: object properties: name: type: string value: type: string data_type: type: string attribute_type: type: string slug: type: string system: type: boolean created_at: type: string example: name: Max cost value: '50.5' data_type: float attribute_type: calculation slug: max_cost system: true created_at: '2018-09-04T16:19:25.343+02:00' Getalistofcustomerattributesresponse: title: Getalistofcustomerattributesresponse required: - data - next_token_starts_after type: object properties: data: type: array items: $ref: '#/components/schemas/CustomerAttributeList' description: '' next_token_starts_after: type: string example: data: - name: Max cost value: '50.5' data_type: float attribute_type: calculation slug: max_cost system: true created_at: '2018-09-04T16:19:25.343+02:00' next_token_starts_after: token Getalistofcustomerattributeresponseerrormut: title: Getalistofcustomerattributeresponseerrormut required: - error - errors type: object properties: error: type: string code: type: string example: - error: attribute_type and attribute_id are mutually exclusive code: invalid_request Getalistofcustomerattributeresponseerror: title: Getalistofcustomerattributeresponseerror required: - error type: object properties: error: type: string example: - error: Internal server error TierLevel: title: TierLevel type: object properties: level: type: integer format: int64 name: type: string threshold: type: number description: Value of the attribute you need to reach to win the level TierData: title: TierData type: object properties: id: type: integer format: int64 name: type: string countries: type: array items: type: string nullable: true description: >- Country where a tier applies, if it applies to all, the field will not appear. current_level_name: type: string description: Tier level name current_level: type: integer description: >- The numerical value of the tier level is always consecutive and in each of the tiers begins with 1. attribute_value: type: integer description: Value of the attribute calculated for the customer won_at: type: string nullable: true description: >- The date on which the tier was won, this date is in UTC (If you have not won the tier yet the field will not appear) expires_at: type: string nullable: true description: >- The date when the tier will expire, it is in UTC, if you convert it to the client's timezone you will see that it expires at 23:59:59 in your timezone. (If you have not won the tier yet the field will not appear) to_reach_next_level_value: type: integer nullable: true description: Remaining value to reach the next level to_reach_next_level_name: type: string nullable: true description: Next level name to reach structure: type: array items: $ref: '#/components/schemas/TierLevel' description: The different levels of which a tier is made up GetAListOfTiersResponse: title: GetAListOfTiersResponse type: object properties: data: type: array items: $ref: '#/components/schemas/TierData' example: data: - id: 1 name: Avg. Spend countries: - ES current_level_name: Bronze current_level: 1 attribute_value: 50 won_at: '2021-05-01T15:00:00Z' expires_at: '2021-12-31T23:59:59Z' to_reach_next_level_value: 50 to_reach_next_level_name: Silver structure: - level: 1 name: Bronze threshold: 0 - level: 2 name: Silver threshold: 100 - level: 3 name: Gold threshold: 200 - id: 2 name: Scores countries: - ES - FR current_level_name: Gold current_level: 3 attribute_value: 250 won_at: '2021-05-01T15:00:00Z' expires_at: '2021-12-31T23:59:59Z' structure: - level: 1 name: Bronze threshold: 0 - level: 2 name: Silver threshold: 100 - level: 3 name: Gold threshold: 200 CustomersGetSegmentValidationResponse: title: CustomersGetSegmentValidationResponse type: object properties: result: type: boolean description: >- It will be `true` if the customer belongs to the segment. Otherwise, it will be `false`. example: result: true CustomersGetListOfSegmentsResponse: title: CustomersGetListOfSegmentsResponse required: - list type: object properties: list: type: array items: type: object properties: segment_id: type: integer format: int64 description: '' example: list: - segment_id: 1234 - segment_id: 5678 CreateaNewAssociationrequest: title: CreateaNewAssociationrequest required: - customer_id - associate_customer_id type: object properties: customer_id: type: integer format: int64 description: ID of the customer in form of an integer. example: 1234 associate_customer_id: type: integer format: int64 description: ID of the associate customer in form of an integer. example: 4321 relationship_type: type: string description: It is the kind of relationship between both customers. example: default active: type: boolean description: >- Status of the association. If not provided the association will be created as active=true by default. example: true main: type: boolean description: >- Indicates the main association. If not provided will be created as main=false by default. example: true CreateaNewAssociationresponse: title: CreateaNewAssociationresponse required: - id - customer_id - associate_customer_id - active - main - created_at - updated_at type: object properties: id: type: integer format: int64 customer_id: type: integer format: int64 associate_customer_id: type: integer format: int64 relationship_type: type: string active: type: boolean main: type: boolean merge_id: type: integer format: int32 customer_kind: type: string associate_code: type: string associate_parent: type: integer format: int64 created_at: type: string updated_at: type: string example: id: 1 customer_id: 1234 associate_customer_id: 4321 relationship_type: default active: true main: true created_at: '2021-09-22T14:02:06.708121Z' updated_at: '2021-09-22T14:02:06.708121Z' UpdateanAssociationrequest: title: UpdateanAssociationrequest required: - customer_id - associate_customer_id - relationship_type type: object properties: customer_id: type: integer format: int64 description: ID of the customer in form of an integer. example: 1234 associate_customer_id: type: integer format: int64 description: ID of the associate customer in form of an integer. example: 4321 relationship_type: type: string description: It is the kind of relationship between both customers. example: default main: type: boolean description: Indicates the main association. If not provided will not change. example: true List: title: List required: - id - customer_id - associate_customer_id - relationship_type - active - created_at - updated_at type: object properties: id: type: integer format: int64 customer_id: type: integer format: int64 associate_customer_id: type: integer format: int64 relationship_type: type: string nullable: true active: type: boolean created_at: type: string updated_at: type: string merge_id: type: integer format: int64 main: type: boolean example: id: 1 customer_id: 999050031793530 associate_customer_id: 999050032283499 relationship_type: null active: true created_at: '2021-09-22T10:45:32.40923Z' updated_at: '2021-09-22T10:45:32.40923Z' Getalistofassociatesresponse: title: Getalistofassociatesresponse required: - list type: object properties: list: type: array items: $ref: '#/components/schemas/List' description: '' example: list: - id: 1 customer_id: 999050031793530 associate_customer_id: 999050032283499 relationship_type: null active: true created_at: '2021-09-22T10:45:32.40923Z' updated_at: '2021-09-22T10:45:32.40923Z' - id: 2 customer_id: 999050031793530 associate_customer_id: 999050032283689 relationship_type: merge active: true merge_id: 1 created_at: '2021-09-22T14:02:06.708121Z' updated_at: '2021-09-22T14:02:06.708121Z' main: true CreateaNewCardassociatedtoaCustomer: title: CreateaNewCardassociatedtoaCustomer type: object properties: id: type: integer description: Id of the new card example: - 331 main: type: boolean description: Indicates the main association. example: - true motive: type: string description: It is the motive for creation of the new card. example: - default relationship_type: type: string description: It is the kind of relationship between customer and the new card. example: - default Mergedatabetweencustomersrequest: title: Mergedatabetweencustomersrequest type: object properties: old_customer_id: type: number description: >- The customer id you want to transfer data from. Exactly one of old_customer_id or old_customer_code must be given. example: 292247 new_customer_id: type: number description: >- The customer id that is going to recieve the data. Exactly one of new_customer_id or nw_customer_code must be given. example: 188976 old_customer_code: type: string description: >- The customer code you want to transfer data from. Exactly one of old_customer_id or old_customer_code must be given. example: '292247' new_customer_code: type: string description: >- The customer code that is going to recieve the data. Exactly one of new_customer_id or nw_customer_code must be given. example: '188976' relationship_type: type: string description: It is the kind of relationship between both customers. example: '"default"' motive: type: string description: It is the motive for merging these two customers. example: '"default"' Mergedatabetweencustomersresponse: title: Mergedatabetweencustomersresponse required: - status type: object properties: status: type: string example: status: success Mergedatabetweencustomersresponse1: title: Mergedatabetweencustomersresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: invalid_request error: Error message Unmergecustomerfromitsparentoneresponse: title: Unmergecustomerfromitsparentoneresponse required: - status type: object properties: status: type: string example: status: success Unmergecustomerfromitsparentoneresponse1: title: Unmergecustomerfromitsparentoneresponse1 required: - code - company - error type: object properties: code: type: string company: type: string error: type: string example: code: invalid_request company: loyal-guru error: Error message Createanewcustomerwiththedataoftheothercustomerrequest: title: Mergedatabetweencustomersrequest type: object properties: old_customer_id: type: number description: >- The customer id you want to transfer data from. Exactly one of old_customer_id or old_customer_code must be given. example: 292247 new_customer_id: type: number description: >- The customer id that is going to recieve the data. Exactly one of new_customer_id or nw_customer_code must be given. example: 188976 old_customer_code: type: string description: >- The customer code you want to transfer data from. Exactly one of old_customer_id or old_customer_code must be given. example: '292247' new_customer_code: type: string description: >- The customer code that is going to recieve the data. Exactly one of new_customer_id or nw_customer_code must be given. example: '188976' relationship_type: type: string description: It is the kind of relationship between both customers. example: default motive: type: string description: It is the motive for merging these two customers. example: default Createanewcustomerwiththedataoftheothercustomerresponse: title: Createanewcustomerwiththedataoftheothercustomerresponse required: - status type: object properties: status: type: string example: status: success Createanewcustomerwiththedataoftheothercustomerresponse1: title: Createanewcustomerwiththedataoftheothercustomerresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: invalid_request error: Error message LineActivity: title: LineActivity required: - order - total - original_total type: object properties: order: type: integer format: int64 description: Order of the line example: 1 product_id: type: integer format: int64 description: >- ID of the product in form of an integer. `product_id` or `product_code` are required and mutually exclusive example: 345 product_code: type: string description: >- Code of the product. `product_id` or `product_code` are required and mutually exclusive example: 0015SJ1L product_ean: type: string description: EAN code of the product. example: GHT567A total: type: number description: >- Total amount of the line payed by the customer ( discounts applied, taxes included ). The sum fo the total of the lines must be equal to the total amount of the activity. If the line belongs to a cancellation activity the total value should be negative. The sum of the total value of all the lines in the database should be equal to the total sales of the company. example: 12.67 original_total: type: number description: Total amount before applying any discount example: 12.67 total_cost: type: number description: Total cost amount of € of the line ( total - total_cost = margin ) example: 9.67 quantity: type: number description: 'Quantity of the elements **(Max value: 999999)**' example: 1.2 measurement_unit: type: string description: |- Type of unit of the quantity. Must be one of this: kg, g, l, m, u example: g total_net: type: number description: Total amount of money paid, taxes not included. example: 1200 total_tax: type: number description: Total amount of money of paid taxes example: 34 product_name: type: string description: Name of the line's product. example: Soda juice 1l product_tax: type: number description: Percentage tax applied to the line's product. example: 21 custom1: type: string deprecated: true description: |- **Use `attributes` instead** Custom Value example: custom value 1 custom2: type: string deprecated: true description: |- **Use `attributes` instead** Custom Value example: custom value 2 custom3: type: string deprecated: true description: |- **Use `attributes` instead** Custom Value example: custom value 3 custom4: type: string deprecated: true description: |- **Use `attributes` instead** Custom Value example: custom value 4 custom5: type: string deprecated: true description: |- **Use `attributes` instead** Custom Value example: custom value 5 custom6: type: string deprecated: true description: |- **Use `attributes` instead** Custom Value example: custom value 6 custom7: type: string deprecated: true description: |- **Use `attributes` instead** Custom Value example: custom value 7 supplier_id: type: number description: Id of the supplier of the product example: 9876 attributes: type: object description: >- Attributes allow you to store additional data on activity lines. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) **Unknown Properties:** Properties not defined in the schema are silently discarded - they won't cause validation errors but will NOT be stored. **Case Sensitivity:** Property names are **case-sensitive** per JSON Schema specification. If your schema defines `ClientId`, sending `CLIENTID` or `clientid` will be treated as unknown properties and silently discarded. Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true additional_costs: type: object description: >- It allows you to store additional costs associated with the cart. > **⚠️ IMPORTANT:**
You must configure the additional costs in the platform.
If an additional cost, sent in the request, does not exist in the platform, the request will fail.

> **Configuration Path:** Configuration > Company > Cart additional costs **Limits:** - The JSON object must have only one level of keys. - Each value must be a number (float). **Example:** ```json { "cost1": 1.17, "cost2": 2.99 } ``` example: cost1: 1.17 cost2: 2.99 Cashback: title: Cashback required: - line_order - discount type: object properties: line_order: type: integer format: int64 description: Order of the line example: 1 score: type: integer format: int64 description: Quantity of score used example: 1234 discount: type: number description: Discount amount example: 1267 Return: title: Return required: - line_order - from_line_order - quantity type: object properties: ticket_id: type: integer format: int64 description: >- `ID` of the original activity where the product was purchased. It's mutually exclusive with `ticket_code`. example: 1234 ticket_code: type: string description: >- `CODE` of the original activity where the product was purchased. It's mutually exclusive with `ticket_id`. example: 1a2b3c4d line_order: type: integer format: int64 description: >- Line order of the **original activity** where the returned item was purchased originally. example: 1 from_line_order: type: integer format: int64 description: >- Line order in the **current activity** of the returned item. It is a line with negative amount. example: 3 quantity: type: number description: >- Quantity of the products that you are returning ( this is meaningfull when you purchased 3 items but you are returning 1 , but in anycase you must send this param ) example: 1 line_order_change: type: integer format: int64 description: >- Line order in the **current activity** that points to the new product in a product change. A product change doesn´t generate or consum scores. example: 1 PromotionV2: title: PromotionV2 required: - promotion_id - discount type: object properties: promotion_id: type: integer format: int64 description: ID of the promotion example: 1234 discount: type: number description: >- Discount amount. Remember that if it is a cancellation then a negative amount should be specified. example: 12.6 line_order: type: integer format: int64 description: Order of the line example: 1 product_id: type: integer format: int64 description: ID of the product example: 2 Payment: title: Payment required: - amount - type type: object properties: amount: type: number description: How much money is paid. example: 15 type: type: string description: >- How the payment is made. Possible values: "card", "cash", "discount", "score". example: cash change: type: number description: Payment's change. example: 5 Shipment: title: Shipment type: object properties: status: type: string description: Shipment status. example: some_status tracking_code: type: string description: Shipment tracking code. example: some_code delivery_address: type: string description: Shipment delivery address. example: some_address company: type: string description: Shipment company. example: some_company tracking_url: type: string description: Shipment tracking url. example: some_url Createanewactivityinrealtimerequest: title: Createanewactivityinrealtimerequest required: - creation_date - total - lines type: object properties: id: type: integer format: int64 description: >- ID of the cart in form of an integer. `id` or `code` are required and mutually exclusive. example: 1234 code: type: string description: >- Identification `code` of the cart in form of an string. `id` or `code` are required and mutually exclusive. **(Length maximum value: 255)** example: 1a2b3c4d location_id: type: integer format: int64 description: >- ID of the location in form of an integer. `location_id` or `location_code` are required and mutually exclusive. example: 12 location_code: type: string description: >- Code of the location. `location_id` or `location_code` are required and mutually exclusive. example: 12A customer_id: type: integer format: int64 description: >- ID of the customer in form of an integer. Mutually exclusive with `customer_code`. example: 8223 customer_code: type: string description: >- Alphanumeric customer code. **It must be unique and existing in ours system**. Mutually exclusive with `customer_id`. example: 8223a creation_date: type: string description: DateTime of the creation of the cart. example: '2016-01-01T23:43:20Z' total: type: number description: >- Total amount of the purchase cart payed by the customer ( dsscounts applied, taxes included ). If the cart is a cancellation this amount should be negative. The sum of the total values of the activities should be equal to the total sales of the company. example: 1234 original_total: type: number description: >- Original total amount of the purchase cart before any discount or cashback applied before evaluation of the ticket in LG. This value never changes in the different evaluations of the same ticket, and it is used to calculate the total discount applied on the ticket. example: 1234 currency: type: string description: >- Code of the currency acording to the [ISO 4217](https://en.wikipedia.org/wiki/List_of_circulating_currencies)(It must be Capitals letters). In the absence of any information on this point, is going to be filled with the default company currency setup. example: EUR cashback_score_desired: type: number description: >- The total amount of points that you'd like to spend on the purchase, if specified a cashback array will appear on the response showing how the points were distributed qithin the cart lines. And also, the total of every line will be modifyied acording this array. Use this param or cashbacks array, but you can's use both. If you don't want to deal with specifying exactly the amount of points for the cashback but you'd like to force the maximum redemption of points available for a certain customer, you can specify "-1". (50% maximum discount by default per each line will be applied) example: 123 vouchers_desired: type: array deprecated: true description: >- **Use `coupons_desired` instead** By default, all massive and loyalty member promotions (points and discounts) are included and applied when calculating the ticket. You can control how vouchers are applied using the `coupons_desired` property: - `all`: Apply all masive + loyalty member promotions + all vouchers assigned to the customer. - `selected`: Apply all massive + loyalty member promotions + only vouchers previously selected by the customer via the appropriate endpoint. - `["34433", "465443"]`: apply all massive + loyalty member promotions without coupon + the vouchers/static code specified. - `[]` (empty array) or omit property: Apply only all massive and loyalty member promotions without coupon (no specific vouchers). example: - selected coupons_desired: type: array description: >- By default, all massive and loyalty member promotions (points and discounts) are included and applied when calculating the ticket. You can control how vouchers are applied using the `coupons_desired` property: - `all`: Apply all masive + loyalty member promotions + all vouchers assigned to the customer. - `selected`: Apply all massive + loyalty member promotions + only vouchers previously selected by the customer via the appropriate endpoint. - `["34433", "465443"]`: apply all massive + loyalty member promotions without coupon + the vouchers/static code specified. - `[]` (empty array) or omit property: Apply only all massive and loyalty member promotions without coupon (no specific vouchers). example: - selected lines: type: array items: $ref: '#/components/schemas/LineActivity' description: Array of lines, at least one is required. cashbacks: type: array items: $ref: '#/components/schemas/Cashback' description: >- Array of cashbacks. Use this param or cashback_score_desired, but you can's use both. returns: type: array items: $ref: '#/components/schemas/Return' description: Array of returns. promotions: type: array items: $ref: '#/components/schemas/PromotionV2' description: >- Array with applied promotions. **Important:** this is only an informative field, you can't apply a promotion through this field. custom1: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom2: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom3: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom4: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom5: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom6: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom7: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom8: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value business_name: type: string description: The company's corporate name. example: SuperMarket S.L. Spain total_net: type: number description: Total amount of money paid by the customer, excluding taxes. example: 1200 total_tax: type: number description: Total amount of taxes paid by the customer. example: 34 tpv_id: type: string description: Alphanumeric identifier of the PoS terminal where the cart is made. example: A55 staff_name: type: string description: Name of the person on the PoS terminal. example: John Doe order_id: type: string description: Alphanumeric identifier of the order the cart belongs to. example: Order 1234A payments: type: array items: $ref: '#/components/schemas/Payment' description: Details how the cart amount is paid. shipment: $ref: '#/components/schemas/Shipment' checkout_date: type: string description: DateTime of the checkout of the cart. example: '2016-01-01T23:43:20Z' payment_cost: type: number description: Total amount of payment cost paid by the customer. example: 1.5 shipping_cost: type: number description: Total amount of shipping cost paid by the customer. example: 5.5 channel: type: string description: Channel from which the cart comes. example: online attributes: type: object description: >- Attributes allow you to store additional data on activities. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) **Unknown Properties:** Properties not defined in the schema are silently discarded - they won't cause validation errors but will NOT be stored. **Case Sensitivity:** Property names are **case-sensitive** per JSON Schema specification. If your schema defines `ClientId`, sending `CLIENTID` or `clientid` will be treated as unknown properties and silently discarded. Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true additional_costs: type: object description: >- It allows you to store additional costs associated with the cart. > **⚠️ IMPORTANT:**
You must configure the additional costs in the platform.
If an additional cost, sent in the request, does not exist in the platform, the request will fail.

> **Configuration Path:** Configuration > Company > Cart additional costs **Limits:** - The JSON object must have only one level of keys. - Each value must be a number (float). **Example:** ```json { "cost1": 1.17, "cost2": 2.99 } ``` example: cost1: 1.17 cost2: 2.99 apply_discounts: type: boolean description: >- It allows you to decide whether discounts should be applied to the cart or not. By default, discounts are applied to the cart. If you set this parameter to false, no discount will be applied to the cart, but points discount will be applied if `cashback_score_desired` or `cashbacks` are specified. example: true apply_points: type: boolean description: >- It allows you to decide whether points campaigns should be applied to the cart or not. By default, points are given to the customer according to the points campaigns configured in the platform. If you set this parameter to false, no points campaign will be given through the cart. This parameter doesn't affect the redemption of points specified through `cashback_score_desired` or `cashbacks`, those points will be redeemed even if `apply_points` is set to false. example: false Customer: title: Customer type: object properties: id: type: integer format: int64 description: Customer id example: 1 score: type: integer format: int64 description: Customer total score example: 1234 score_as_money: type: number description: Customer total score as discount money example: 12.34 score_available: type: integer format: int64 description: Customer available score example: 1204 score_available_as_money: type: string description: Customer available score as discount money example: 12.04 score_threshold_cashback: type: integer format: int64 description: The minimum score needed to allow cashback example: 1000 score_threshold_cashback_as_money: type: number description: The minimum score needed to allow cashback as discount money example: 100 money_threshold_cashback: type: number description: Minimum money needed to spend in order to allow cashback example: 10 score_to_reach_cashback: type: integer format: int64 description: >- Missing score that is needed by the customer in order to reach cashback. This is the difference between score_threshold_cashback and score_available example: 100 money_to_spend_to_reach_cashback: type: number description: >- Missing money that the customer must spend in order to reach cashback. This is score_to_reach_cashback * money_threshold_cashback / score_threshold_cashback example: 0.1 fraudulent: type: boolean description: If the customer is fraudulent or not example: false attributes: type: object description: >- Attributes allow you to store additional data on customers. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "loyalty_tier": "gold", "customer_score": 850, "newsletter_opt_in": true, "tags": ["vip", "premium", "early_adopter"], "preferred_store_ids": [101, 205, 308], "interests": ["electronics", "fashion", "sports"] } ``` example: loyalty_tier: gold customer_score: 850 newsletter_opt_in: true tags: - vip - premium - early_adopter preferred_store_ids: - 101 - 205 - 308 interests: - electronics - fashion - sports EffectsVoucherInfo: title: EffectsVoucherInfo type: object description: >- Information about the voucher (if the efect is related to a targeted campaign only) properties: voucher_id: description: The ID of the voucher type: integer example: 1001 voucher_code: description: The code of the voucher type: string example: '23222' coupon_id: description: The ID of the coupon type: integer example: 3222 coupon_name: description: The name of the coupon type: string example: €5 total cart static_code: description: The static code of the coupon (optional) type: string example: SALES89 Effects: title: Effects type: object properties: rule_id: description: The ID of the promotion campaign. type: integer example: 2322 line: description: > Line (equivalent to line_order) where this effect applies. For total cart effects, line is not included. type: integer example: 1 rule_name: description: The name of the promotion campaign. type: string example: €5 total cart type: description: 'Type of the promotion campaign. Options: "discount" , "points"' type: string example: discount effect_type: type: string description: |- Type of the effect applied. Possible options: --- ### **Percentage Strategy** **Key:** `percentage` Applies a percentage-based calculation. * **Value (decimal, > 0):** The percentage to apply (e.g., `0.8` for 0.8%, `5.0` for 5%). * **For Discounts:** Applies the specified percentage value as a discount. * **For Points:** Accumulates points by calculating the percentage of the amount of each line item on the cart, then converting it to its equivalent in points. This supports decimal values (e.g., `0.8%`). --- ### **Direct Value Strategy** **Key:** `direct_value` Applies a fixed monetary or point value. * **Value (decimal, > 0):** The fixed amount to apply. * **For Discounts:** Applies a fixed discount value (e.g., a value of `5` applies a $5 discount). * **For Points:** Awards a fixed number of points (e.g., a value of `100` awards 100 points). --- ### **Ratio Strategy** **Key:** `ratio` Defines a ratio for earning (e.g., "every X amount, give Y points/discount"). * **Input Value (integer, > 0):** The base value (the 'X' in 'Every X...'). * **Output Value (integer, > 0):** The value to be given (the 'Y' in '...give Y...'). * **For Discounts:** Applies a discount based on the defined ratio (e.g., Input = `100`, Output = `10` means "every $100 spent, get $10 discount"). * **For Points:** Awards points based on the defined ratio (e.g., Input = `1`, Output = `10` means "every $1 spent, get 10 points"). --- ### **Strikethrough Strategy** **Key:** `strikethrough` Sets a specific final price for selected products, overriding their original pricing. This strategy **does not consider** conditions or traditional application rules. * **For Discounts:** The `final_price` for each `product_id` (considering quantity) replaces the original total price for that product in the engine, effectively applying a discount. * **For Points:** The `final_price` for each `product_id` (considering quantity) is used as the base value for points accumulation in the customer's wallet. --- ### **Combo Price Strategy** **Key:** `combo_price` Sets a fixed combined price for a group of selected products. * **Value (numeric, > 0):** The desired final total price for the combo. * **Application:** The difference between the original total price of the combo items and the `combo_price` is distributed as a discount across all participating lines or total cart. * **Example:** If 2 Cokes and 1 Sandwich originally cost $15, but the combo price is set to $10, the $5 difference ($15 - $10) will be divided among the 3 lines. --- ### **Coupon rollback** **Key:** `rollback` Sets a fixed combined price for a group of selected products. * **Application:** This effect is used to reverse the impact of a previously applied coupon when there is a return or refund. * **Example:** If a customer returns an item that was purchased with a coupon, this effect will reverse the usage of the coupon. example: percentage distribution_type: description: >- Understanding Loyalty Distribution Strategies: --- **Total** **Key:**: `total` This strategy applies the discount or points to the **entire cart total** rather than distributing them among individual line items. * **Applies to:** All loyalty operations **except Strikethrough**. Strikethrough operations cannot use this distribution method. --- **Individual Items** **Key:**: `individual_items` With this strategy, the discount or points are distributed **line by line**. Depending on the specific loyalty effect, this might involve: * Calculating the effect per line. * Calculating the total effect first and then distributing it proportionally among the lines. In the latter case, a line will only receive up to its value (e.g., if you're distributing €10 per line and a line costs €8, it will only receive an €8 discount). * **Applies to:** All loyalty operations, with specific considerations: * **Direct Value Operation:** If the operation is "Direct Value," the specified value is applied directly to *each* line item. For example, if the Direct Value is €2, then €2 will be discounted from each line, or 2 points will be awarded for each line. The value isn't distributed; it applies individually to every line. --- **Individual Items Pro Rata** **Key:**: `individual_items_pro_rata` This strategy also distributes the discount or points **line by line**, but it does so **proportionally based on each line's total value**. This ensures that larger value lines receive a larger portion of the discount or points. When applying loyalty effects like discounts or points, we offer different distribution strategies to control how these values are allocated across a customer's cart. type: string example: individual_items select_customers: description: >- Determines the **customer segment** to which this rule applies. This allows you to specify whether the rule is valid for: + **Loyalty Members (`loyalty`):** Only customers actively enrolled in a loyalty program. + **Targeted Customers (`targeted`):** A specific subset of customers identified through particular criteria (e.g., via a segment). + **All Customers (`all_customers`):** Every customer, regardless of their loyalty status or other targeting. type: string example: loyalty value: description: >- when discount: The value of the discount in cents. You decide how to process it. when points: the value of points given by the effect. If the effectype is "rollback" this value is negative if there are points to remove from the wallet and positive if there are points to add to the wallet (because points were used to pay in the original cart). type: number example: 20 value_as_money: description: >- when points: The money equivalence of points based on the score exchange value for the currency (in cents) type: number example: 2000 available_from: description: 'when points: Date when earned points become available for use' type: number example: '2025-01-02' available_to: description: 'when points: Date when earned points expire' type: number example: '2025-08-02' coupon_info: nullable: true $ref: '#/components/schemas/EffectsVoucherInfo' application_path: nullable: true description: >- Specifies the application path where the effect is applied. The application_path is mainly used when the effect applies at the application level and is not associated with a specific line of the cart. Examples: * "application_path": "payments.1.amount". When the effect is applied to a payment method, the application path indicates the specific payment method and amount field to which the effect applies. In this example, "payments.1.amount" refers to the amount field of the second payment method in the cart (index starts at 0). * "application_path": "additional_costs.shipping". When the effect is applied to an additional cost, the application path indicates the specific additional cost and its field to which the effect applies. In this example, "additional_costs.shipping" refers to the shipping additional cost in the cart. type: string example: additional_costs.shipping RejectedCampaign: title: RejectedCampaign type: object properties: rule_id: description: | The ID of the campaign. type: integer example: 1 rule_name: description: The name of the campaign. type: string example: €5 total cart type: description: 'Type of the promotion campaign. Options: "discount" , "points"' type: string example: discount error: type: string description: >- Reason why the campaign, voucher or coupon was rejected. Possible values: - The campaign cannot be applied because the cart does not meet the victory conditions. Message: The cart does not contain the victory conditions specified in the campaign - The campaign cannot be applied because the cart does not meet the application conditions. The cart does not contain the victory conditions specified in the campaign. - The campaign cannot be applied because the cart does not meet the configured effect conditions. The cart does not contain the victory conditions specified in the campaign. - The campaign cannot be used because the campaign exceeds the limits - Campaign budget. Message: The campaign budget was reached - Campaign usage. Message: The total coupon usage was reached - Customer redemption limit Message: The customer specific redemption limit has been reach - Maximum discount transaction . Message: The total campaign discount in this event has been reached. example: The campaign budget was reached coupon_info: nullable: true $ref: '#/components/schemas/EffectsVoucherInfo' Coupon: title: Coupon nullable: true type: object properties: id: description: The ID of the coupon. type: integer format: int64 key: description: The key of the coupon. type: string name: type: string example: Discount meat 50% description: Name of the coupon from which the voucher comes description: type: string example: Discount meat 50% extended description description: Voucher description max_redemptions: description: The maximum number of redemptions for this coupon. type: integer format: int64 min_money: description: The minimum amount of money to spend for this coupon. type: number format: int64 max_money: description: The maximum amount of money to spead for this coupon. type: number min_units: description: The minimum anount of units to buy for this coupon. type: integer format: int64 max_units: description: The maxium anount of units to buy for this coupon. type: integer format: int64 discount: description: The discount for this coupon. type: number discount_type: description: The type of the discount for this coupon. type: string affectation: description: The affectation for this coupon. type: string example: id: 123 key: discountkeyreferencing internal promo name: ' Discount meat 50%' description: Discount meat 50% extended description max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash affectation: activity VoucherActivityResponse: title: VoucherActivityResponse type: object properties: voucher_id: type: integer description: Id of the voucher example: 13009014 voucher_code: type: string description: Code of the voucher example: '13993492' discount: type: number description: >- Discount amount in cents. Remember that if is a cancellation a negative amount should be specified. example: 1267 line_order: type: integer format: int64 description: Order of the line example: 1 product_id: type: integer format: int64 description: ID of the product if applies example: 2 rule_id: type: integer description: Promotional campaign id if applies example: 2 coupon: $ref: '#/components/schemas/Coupon' Cashback_returns: title: Cashback_returns type: object properties: line_order: type: integer format: int64 description: Order of the line example: 1 score: type: integer format: int64 description: Quantity of score returned to the customer example: 1234 Scores1: title: Scores1 required: - line_order - score - loyalty_score_id type: object properties: line_order: type: integer format: int64 score: type: integer format: int64 loyalty_score_id: type: integer format: int64 available_from: type: string available_to: type: string example: line_order: 1 score: 100 loyalty_score_id: 2 available_from: '2020-01-01' available_to: '2021-01-01' PromotionV3: title: PromotionV3 type: object properties: promotion_id: type: integer format: int64 description: ID of the promotion example: 1234 discount: type: number description: >- Discount amount. Remember that if it is a cancellation then a negative amount should be specified. example: 12.6 line_order: type: integer format: int64 description: Order of the line example: 1 product_id: type: integer format: int64 description: ID of the product example: 2 Createanewactivityinrealtimeresponse: title: Createanewactivityinrealtimeresponse type: object properties: id: type: integer format: int64 description: Unique identifier of the cart. example: 123456 code: type: string description: Code of the cart. example: ACT-123456 creation_date: type: string format: date-time description: Date and time of the cart. example: '2025-06-01T12:00:00Z' location_id: type: integer format: int64 description: Unique identifier of the location where the cart was created. example: 98765 total: type: number description: Total amount of the cart after applying all discounts. example: 100.5 original_total: type: number description: Original total amount of the cart before applying any discounts. example: 150.75 score: type: integer format: int64 description: Total amount of points win in a cart by all points campaigns example: 100 score_as_money: type: number description: >- Total amount of discount money won in this cart by all points campaigns example: 12.65 score_used: type: integer format: int64 description: Total amount of points used in a cart. example: 120 score_used_as_money: type: number description: Total amount of discount money (by points burned) used in a cart. example: 12.65 score_returned_from_customer: type: integer format: int64 description: Total amount of points that customer lost in a return. example: 12 score_returned_from_customer_as_money: type: number description: >- Total amount of discount money (considering points) that customer lost in a return. example: 1.25 score_returned_to_customer: type: integer format: int64 description: Total amount of points that customer win in a return. example: 12 score_returned_to_customer_as_money: type: number description: >- Total amount of discount money that customer win in a return by points returned. example: 1.25 total_scores_coupon_applied: type: number description: Total amount of scores won by coupons within the cart example: 116 total_scores_coupon_applied_as_money: type: number description: >- Total amount of money won by points coupons within the cart (total_scores_coupon_applied money equivalent) example: 1.16 total_discount_voucher_applied: type: number description: >- Total amount of discount money applied by targeted coupons within the cart example: 11.2 total_discount_applied: type: number description: >- Total amount of discount money applied by all discount campaigns within the cart example: 11.2 lines: type: array items: $ref: '#/components/schemas/LineActivity' description: | Array of lines. **Important** + The **`total`** amount of returned lines on the cart is adjusted after applying all relevant discounts, including those from promotional campaigns, vouchers, and any point-based discounts (cashback). + The original, unadjusted amount for each line item remains unchanged and is preserved in the **`original_total`** attribute. customer: type: array items: $ref: '#/components/schemas/Customer' description: > Provides supplementary information about the customer, relevant to the current purchase, only if the customer is identified in the transaction. effects: type: array items: $ref: '#/components/schemas/Effects' description: > This section provides a comprehensive overview of all loyalty effects applied to the purchase, encompassing both points-earning and discount-based campaigns. example: - rule_id: 2322 line: 1 rule_name: Product Discount type: discount effect_type: percentage distribution_type: individual_items select_customers: loyalty value: 100 - rule_id: 2323 line: -1 rule_name: Holiday Points Bonus type: points effect_type: direct_value distribution_type: total select_customers: all_customers value: 600 value_as_money: 6 available_from: '2025-06-01' available_to: '2026-05-30' - rule_id: 2324 line: 2 rule_name: Combo Meal Deal type: discount effect_type: combo_price distribution_type: individual_items_pro_rata select_customers: targeted value: 400 coupon_info: voucher_id: 111 voucher_code: 4344fjaa coupon_id: 122211 coupon_name: Combo Meal Deal - rule_id: 2325 line: 3 rule_name: Cashback Offer type: points effect_type: ratio distribution_type: total select_customers: loyalty value: 600 value_as_money: 6 available_from: '2025-06-01' available_to: '2026-05-30' - type: discount rule_id: 23224 rule_name: Discount 15% promo distribution_type: individual_items select_customers": targeted effect_type: rollback line: 6 value: 400 coupon_info: voucher_id: 222 voucher_code: sale190 coupon_id: 12311 coupon_name: Sales discount example - type: points effect_type: rollback rule_id: 12313 rule_name: Double points promo Weekends distribution_type: individual_items select_customers": targeted line: 7 value: -200 coupon_info: voucher_id: 223 voucher_code: doublepoints coupon_id: 12312 coupon_name: Double points campaign rejected_campaigns: type: array items: $ref: '#/components/schemas/RejectedCampaign' description: >- This attribute lists all campaigns , vouchers or coupons that were attempted to be applied to the cart but were rejected, along with the reasons for their rejection. invalid_coupons: type: array description: >- This attribute contains a list of all vouchers or coupons specified in `coupons_desired` that are either invalid or do not exist vouchers: type: array items: $ref: '#/components/schemas/VoucherActivityResponse' description: >- This attribute is returned exclusively when targeted campaign vouchers have been successfully applied to the purchase. cashbacks: type: array items: $ref: '#/components/schemas/Cashback' description: > When the `cashback_score_desired` field is provided in the request, the points designated for burning (redemption) are distributed across all eligible lines within the transaction. This array details, for each individual line item, the quantity of points that were burned and their equivalent monetary discount. cashback_returns: type: array items: $ref: '#/components/schemas/Cashback_returns' description: > This attribute is present when the cart involves returned items. It visualizes all points that were originally redeemed (used for discounts) in the initial purchase and are now being returned to the customer as part of the return transaction. scores: type: array items: $ref: '#/components/schemas/Scores1' description: > This section displays a detailed breakdown, line by line, of all loyalty points earned with the current purchase. vouchers_desired: type: array deprecated: true description: >- **Use `coupons_desired` instead** 'Vouchers sent in the request are those the user intended to apply. If the request included "selected", this field will list all vouchers the customer selected and attempted to apply to the ticket. Note: This does not confirm the vouchers were successfully applied. To see which vouchers were actually applied, refer to the vouchers field.' coupons_desired: type: array description: >- 'Coupons sent in the request are those the user intended to apply. If the request included "selected", this field will list all coupons the customer selected and attempted to apply to the ticket. Note: This does not confirm the coupons were successfully applied. To see which coupons were actually applied, refer to the vouchers field.' promotions: type: array deprecated: true items: $ref: '#/components/schemas/PromotionV3' description: >- This is only an informative field, you can't apply a promotion through this field. attributes: type: object description: >- Attributes allow you to store additional data on activities. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true additional_costs: type: object description: >- It allows you to store additional costs associated with the cart. > **⚠️ IMPORTANT:**
You must configure the additional costs in the platform.
If an additional cost, sent in the request, does not exist in the platform, the request will fail.

> **Configuration Path:** Configuration > Company > Cart additional costs > **Considerations:** If there are any campaigns applying to a field of the additional costs, the value of that field will be adjusted after applying the campaign discount. The original value of the additional cost, before applying any discount, will be preserved in the `original_` field (e.g., if the additional cost field is `cost1`, the original value will be in `original_cost1`). **Limits:** - The JSON object must have only one level of keys. - Each value must be a number (float). **Example:** ```json { "cost1": 1.17, "cost2": 2.99, "original_cost1": 1.50, "original_cost2": 3.50 } ``` example: cost1: 1.17 cost2: 2.99 original_cost1: 1.5 original_cost2: 3.5 Simulatethecreationofanewactivityinrealtimerequest: title: Simulatethecreationofanewactivityinrealtimerequest required: - creation_date - total - lines type: object properties: id: type: integer format: int64 description: >- ID of the cart in form of an integer. `id` or `code` are required and mutually exclusive. example: 1234 code: type: string description: >- Identification `code` of the cart in form of an string. `id` or `code` are required and mutually exclusive. **(Length maximum value: 255)** example: 1a2b3c4d location_id: type: integer format: int64 description: >- ID of the location in form of an integer. `location_id` or `location_code` are required and mutually exclusive. example: 12 location_code: type: string description: >- Code of the location. `location_id` or `location_code` are required and mutually exclusive. example: 12A customer_id: type: integer format: int64 description: >- ID of the customer in form of an integer. Mutually exclusive with `customer_code`. example: 8223 customer_code: type: string description: >- Alphanumeric customer code. **It must be unique and existing in ours system**. Mutually exclusive with `customer_id`. example: 8223a creation_date: type: string description: DateTime of the creation of the cart. example: '2016-01-01T23:43:20Z' total: type: number description: >- Total amount of the purchase cart payed by the customer ( dsscounts applied, taxes included ). If the cart is a cancellation this amount should be negative. The sum of the total values of the activities should be equal to the total sales of the company. example: 1234 original_total: type: number description: >- Original total amount of the purchase cart before any discount or cashback applied before evaluation of the ticket in LG. This value never changes in the different evaluations of the same ticket, and it is used to calculate the total discount applied on the ticket. example: 1234 currency: type: string description: >- Code of the currency acording to the [ISO 4217](https://en.wikipedia.org/wiki/List_of_circulating_currencies)(It must be Capitals letters). In the absence of any information on this point, is going to be filled with the default company currency setup. example: EUR cashback_score_desired: type: number description: >- The total amount of points that you'd like to spend on the purchase, if specified a cashback array will appear on the response as a recommendation on how should you distribute the score in the different lines. And also, the total of every line will be modifyied acording this array.Use this param or cashbacks array, but you can's use both. If you don't want to deal with specifying exactly the amount of points for the cashback but you'd like to force the maximum redemption of points available for a certain customer, you can specify "-1". example: 123 vouchers_desired: type: array deprecated: true description: >- **Use coupons_desired instead** By default, all massive and loyalty member promotions (points and discounts) without coupon are included and applied when calculating the ticket. You can control how vouchers are applied using the `coupons_desired` property: - `all`: Apply all masive + loyalty member promotions + all vouchers assigned to the customer. - `selected`: Apply all massive + loyalty member promotions + only vouchers previously selected by the customer via the appropriate endpoint. - `["34433", "465443"]`: apply all massive + loyalty member promotions without coupon + the vouchers/static code specified. - `[]` (empty array) or omit property: Apply only all massive and loyalty member promotions without coupon (no specific vouchers). example: - selected coupons_desired: type: array description: >- By default, all massive and loyalty member promotions (points and discounts) are included and applied when calculating the ticket. You can control how vouchers are applied using the `coupons_desired` property: - `all`: Apply all masive + loyalty member promotions + all vouchers assigned to the customer. - `selected`: Apply all massive + loyalty member promotions + only vouchers previously selected by the customer via the appropriate endpoint. - `["34433", "465443"]`: apply all massive + loyalty member promotions without coupon + the vouchers/static code specified. - `[]` (empty array) or omit property: Apply only all massive and loyalty member promotions without coupon (no specific vouchers).. example: - selected lines: type: array items: $ref: '#/components/schemas/LineActivity' description: Array of lines, at least one is required. cashbacks: type: array items: $ref: '#/components/schemas/Cashback' description: >- Array of cashbacks. Use this param or cashback_score_desired, but you can's use both. returns: type: array items: $ref: '#/components/schemas/Return' description: Array of returns. promotions: type: array items: $ref: '#/components/schemas/PromotionV2' description: >- Array with applied promotions. **Important:** this is only an informative field, you can't apply a promotion through this field. custom1: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom2: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom3: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom4: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom5: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom6: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom7: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value custom8: deprecated: true oneOf: - type: string description: |- **Use `attributes` instead** it has a limit of 255 characters example: custom value - type: object description: |- **Use `attributes` instead** it has a limit of 1048487 bytes example: custom_key: custom_value business_name: type: string description: The company's corporate name. example: SuperMarket S.L. Spain total_net: type: number description: Total amount of money paid by the customer, excluding taxes. example: 1200 total_tax: type: number description: Total amount of taxes paid by the customer. example: 34 tpv_id: type: string description: Alphanumeric identifier of the PoS terminal where the cart is made. example: A55 staff_name: type: string description: Name of the person on the PoS terminal. example: John Doe order_id: type: string description: Alphanumeric identifier of the order the cart belongs to. example: Order 1234A payments: type: array items: $ref: '#/components/schemas/Payment' description: Details how the cart amount is paid. shipment: $ref: '#/components/schemas/Shipment' checkout_date: type: string description: DateTime of the checkout of the cart. example: '2016-01-01T23:43:20Z' payment_cost: type: number description: Total amount of payment cost paid by the customer. example: 1.5 shipping_cost: type: number description: Total amount of shipping cost paid by the customer. example: 5.5 channel: type: string description: Channel from which the cart comes. example: online attributes: type: object description: >- Attributes allow you to store additional data on activities. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true additional_costs: type: object description: >- It allows you to store additional costs associated with the cart. > **⚠️ IMPORTANT:**
You must configure the additional costs in the platform.
If an additional cost, sent in the request, does not exist in the platform, the request will fail.

> **Configuration Path:** Configuration > Company > Cart additional costs **Limits:** - The JSON object must have only one level of keys. - Each value must be a number (float). **Example:** ```json { "cost1": 1.17, "cost2": 2.99 } ``` example: cost1: 1.17 cost2: 2.99 apply_discounts: type: boolean description: >- It allows you to decide whether discounts should be applied to the cart or not. By default, discounts are applied to the cart. If you set this parameter to false, no discount will be applied to the cart, but points discount will be applied if `cashback_score_desired` or `cashbacks` are specified. example: true apply_points: type: boolean description: >- It allows you to decide whether points campaigns should be applied to the cart or not. By default, points are given to the customer according to the points campaigns configured in the platform. If you set this parameter to false, no points campaign will be given through the cart. This parameter doesn't affect the redemption of points specified through `cashback_score_desired` or `cashbacks`, those points will be redeemed even if `apply_points` is set to false. example: false Simulatethecreationofanewactivityinrealtimeresponse: title: Simulatethecreationofanewactivityinrealtimeresponse type: object properties: id: type: integer format: int64 description: Unique identifier of the cart. example: 123456 code: type: string description: Code of the cart. example: ACT-123456 creation_date: type: string format: date-time description: Date and time of the cart. example: '2025-06-01T12:00:00Z' location_id: type: integer format: int64 description: Unique identifier of the location where the cart was created. example: 98765 total: type: number description: Total amount of the cart after applying all discounts. example: 100.5 original_total: type: number description: Original total amount of the cart before applying any discounts. example: 150.75 score: type: integer format: int64 description: Total amount of points win in a cart. example: 100 score_as_money: type: number description: Total amount of money won in this cart. example: 12.65 score_used: type: integer format: int64 description: Total amount of points used in a cart. example: 120 score_used_as_money: type: number description: Total amount of discount money used (by points burned) in a cart. example: 12.65 score_returned_from_customer: type: integer format: int64 description: Total amount of points that customer lost in a return. example: 12 score_returned_from_customer_as_money: type: number description: >- Total amount of discount money (considering points) that customer lost in a return. example: 1.25 score_returned_to_customer: type: integer format: int64 description: Total amount of points that customer win in a return. example: 12 score_returned_to_customer_as_money: type: number description: >- Total amount of discount money that customer win in a return by points returned. example: 1.25 total_scores_coupon_applied: type: number description: Total amount of scores won by coupons within the cart example: 116 total_scores_coupon_applied_as_money: type: number description: >- Total amount of money won by points coupons within the cart (total_scores_coupon_applied money equivalent) example: 1.16 total_discount_voucher_applied: type: number description: >- Total amount of discount money applied by targeted vouchers within the cart example: 11.2 total_discount_applied: type: number description: >- Total amount of discount money applied by all discount campaigns within the cart example: 11.2 lines: type: array items: $ref: '#/components/schemas/LineActivity' description: | Array of lines. **Important** + The **`total`** amount of returned lines on the cart is adjusted after applying all relevant discounts, including those from promotional campaigns, vouchers, and any point-based discounts (cashback). + The original, unadjusted amount for each line item remains unchanged and is preserved in the **`original_total`** attribute. customer: type: array items: $ref: '#/components/schemas/Customer' description: > Provides supplementary information about the customer, relevant to the current purchase, only if the customer is identified in the transaction. effects: type: array items: $ref: '#/components/schemas/Effects' description: > This section provides a comprehensive overview of all loyalty effects applied to the purchase, encompassing both points-earning and discount-based campaigns. example: - rule_id: 2322 line: 1 rule_name: Product Discount type: discount effect_type: percentage distribution_type: individual_items select_customers: loyalty value: 100 - rule_id: 2323 line: -1 rule_name: Holiday Points Bonus type: points effect_type: direct_value distribution_type: total select_customers: all_customers value: 600 value_as_money: 6 available_from: '2025-06-01' available_to: '2026-05-30' - rule_id: 2324 line: 2 rule_name: Combo Meal Deal type: discount effect_type: combo_price distribution_type: individual_items_pro_rata select_customers: targeted value: 400 coupon_info: voucher_id: 111 voucher_code: 4344fjaa coupon_id: 122211 coupon_name: Combo Meal Deal - rule_id: 2325 line: 3 rule_name: Cashback Offer type: points effect_type: ratio distribution_type: total select_customers: loyalty value: 600 value_as_money: 6 available_from: '2025-06-01' available_to: '2026-05-30' - type: discount rule_id: 23224 rule_name: Discount 15% promo distribution_type: individual_items select_customers": targeted effect_type: rollback line: 6 value: 400 coupon_info: voucher_id: 222 voucher_code: sale190 coupon_id: 12311 coupon_name: Sales discount example - type: points effect_type: rollback rule_id: 12313 rule_name: Double points promo Weekends distribution_type: individual_items select_customers": targeted line: 7 value: -200 coupon_info: voucher_id: 223 voucher_code: double points coupon_id: 12312 coupon_name: Double points campaign rejected_campaigns: type: array items: $ref: '#/components/schemas/RejectedCampaign' description: >- This attribute lists all vouchers or coupons that were attempted to be applied to the cart but were rejected, along with the reasons for their rejection. invalid_coupons: type: array description: >- This attribute contains a list of all vouchers or coupons specified in `coupons_desired` that are either invalid or do not exist vouchers: type: array items: $ref: '#/components/schemas/VoucherActivityResponse' description: >- This attribute is returned exclusively when targeted campaign vouchers have been successfully applied to the purchase. cashbacks: type: array items: $ref: '#/components/schemas/Cashback' description: > When the `cashback_score_desired` field is provided in the request, the points designated for burning (redemption) are distributed across all eligible lines within the transaction. This array details, for each individual line item, the quantity of points that were burned and their equivalent monetary discount. cashback_returns: type: array items: $ref: '#/components/schemas/Cashback_returns' description: > This attribute is present when the cart involves returned items. It visualizes all points that were originally redeemed (used for discounts) in the initial purchase and are now being returned to the customer as part of the return transaction. scores: type: array items: $ref: '#/components/schemas/Scores1' description: > This section displays a detailed breakdown, line by line, of all loyalty points earned with the current purchase. vouchers_desired: type: array deprecated: true description: >- **Use `coupons_desired` instead** 'Vouchers sent in the request are those the user intended to apply. If the request included "selected", this field will list all vouchers the customer selected and attempted to apply to the ticket. Note: This does not confirm the vouchers were successfully applied. To see which vouchers were actually applied, refer to the vouchers field.' coupons_desired: type: array description: >- 'Coupons sent in the request are those the user intended to apply. If the request included "selected", this field will list all coupons the customer selected and attempted to apply to the ticket. Note: This does not confirm the coupons were successfully applied. To see which coupons were actually applied, refer to the vouchers field.' promotions: type: array deprecated: true items: $ref: '#/components/schemas/PromotionV3' description: >- This is only an informative field, you can't apply a promotion through this field. attributes: type: object description: >- Attributes allow you to store additional data on activities. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true additional_costs: type: object description: >- It allows you to store additional costs associated with the cart. > **⚠️ IMPORTANT:**
You must configure the additional costs in the platform.
If an additional cost, sent in the request, does not exist in the platform, the request will fail.

> **Configuration Path:** Configuration > Company > Cart additional costs > **Considerations:** If there are any campaigns applying to a field of the additional costs, the value of that field will be adjusted after applying the campaign discount. The original value of the additional cost, before applying any discount, will be preserved in the `original_` field (e.g., if the additional cost field is `cost1`, the original value will be in `original_cost1`). **Limits:** - The JSON object must have only one level of keys. - Each value must be a number (float). **Example:** ```json { "cost1": 1.17, "cost2": 2.99, "original_cost1": 1.50, "original_cost2": 3.50 } ``` example: cost1: 1.17 cost2: 2.99 Line: title: Line type: object properties: order: type: integer format: int64 description: Line order in the activity. example: 1 total: type: number description: Total amount of the activity line. example: 100 total_net: type: number description: Total amount of money paid, taxes not included. example: 1200 quantity: type: number description: Quantity of products on this line. example: 100 product_code: type: string description: Code of the product. example: ERMP4L3 product_id: type: integer format: int64 description: ID of the product. example: 1567567 product_ean: type: string description: EAN code of the product. example: GHT567A product_name: type: string description: Name of the product. example: Example product product_tax: type: number description: Tax associated to the product. example: 100 total_cost: type: number description: Total amount of the line. example: 100 original_total: type: number description: Original amount of the line. example: 100 custom1: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 1 of activity line. example: tryit custom2: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 2 of the activity line. example: custom custom3: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 3 of the activity line. example: custom custom4: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 4 of the activity line. example: custom custom5: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 5 of the activity line. example: custom custom6: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 6 of the activity line. example: custom custom7: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 7 of the activity line. example: custom custom9: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 9 of the activity line. example: custom measurement_unit: type: string description: Measurement unit of the line. example: u attributes: type: object description: >- Attributes allow you to store additional data on activity lines. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true scores: title: scores type: object properties: score: type: integer format: int64 description: Total amount of points won with this loyalty score. example: 100 line_order: type: integer format: int64 description: Line order were the loyalty score is won. example: 12 loyalty_score_id: type: integer format: int64 description: ID of loyalty rule. example: 12 available_from: type: string format: date description: Date from when the points won are available. example: '2026-05-01' available_to: type: string format: date description: Date to when the points won are available. example: '2026-05-27' payments: title: payments type: object properties: amount: type: number description: Total amount of the payment method. example: 100 change: type: number description: Change amount to be returned of the payment method. example: 12 type: type: string description: Type of the payment method. example: cash status_histories: title: status_histories type: object properties: status: type: string description: Status of the shipment on this moment. example: '1' created_at: type: string description: Date of the status change. example: '1' shipment1: title: shipment1 type: object properties: status: type: string description: Actual status of shipment. example: '1' tracking_code: type: string description: Tracking code of shipment. example: '1' delivery_address: type: string description: Delivery address of shipment. example: '1' company: type: string description: Company name of shipment. example: '1' tracking_url: type: string description: Tracking URL of shipment. example: '1' status_histories: type: array items: $ref: '#/components/schemas/status_histories' description: '' cashbacks: title: cashbacks type: object properties: line_order: type: integer format: int64 description: e order of were the cashback is applied. example: 12 score: type: integer format: int64 description: Total amount of points used on this cashback line. example: 100 discount: type: integer format: int64 description: Discount applied on the activity line. example: 4.96 returns: title: returns type: object properties: ticket_id: type: integer format: int64 description: ID of the original activity. example: 100 ticket_code: type: string description: ID of the original activity. example: a1b2c34d score: type: integer format: int64 description: Total amount of points returned on this line. example: 100 quantity: type: number description: Returned quantity in the described line. example: 100 line_order: type: integer format: int64 description: Line order in the original line. example: 12 from_line_order: type: integer format: int64 description: Line order in the current activity. example: 10 line_order_change: type: integer format: int64 description: If it is a product change the line order of the new product. example: 112 cashback_returns1: title: cashback_returns1 type: object properties: line_order: type: integer format: int64 description: >- Line in the current activity associated to the return of scores due to cashback. example: 12 score: type: integer format: int64 description: Total amount of points returned on this cashback line. example: 100 Getanactivityresponse: title: Getancartresponse type: object properties: id: type: integer format: int64 description: ID of the cart. example: 100 currency: type: string description: Currency of the cart. example: EUR code: type: string description: Code of the cart if provided on creation. example: 43433fsss-ihjyw total: type: number description: Total amount of the cart. example: 12 location_id: type: integer format: int64 description: ID of location that cart was created. example: 120 location_code: type: string description: Code of location that cart was created if provided on creation. example: '1234567890' customer_id: type: integer format: int64 description: ID of customer that created the cart. example: 100 customer_code: type: string description: Code of customer that created the cart. example: '1234567890' customer: $ref: '#/components/schemas/Customer' creation_date: type: string description: Date and time of the cart sent on creation. example: '2026-05-27T00:00:00' lines: type: array items: $ref: '#/components/schemas/Line' description: '' scores: type: array items: $ref: '#/components/schemas/scores' description: '' business_name: type: string description: Name of the company associated to the cart. example: '100' payments: type: array items: $ref: '#/components/schemas/payments' description: payment methods used in the cart score: type: integer format: int64 description: Total amount of points won in the cart. example: 100 score_as_money: type: number description: Total amount of discount money won in the cart (points equivalent). example: 12.34 score_used: type: integer format: int64 description: Total amount of points used in the cart. example: 120 score_used_as_money: type: number description: Total amount of discount money used in the cart (points equivalent). example: 12.34 score_returned_to_customer: type: integer format: int64 description: >- Total amount of points that the company returned to the customer due to a product return. example: 12 score_returned_to_customer_as_money: type: number description: >- Total amount of discount money returned to the customer in the cart (points equivalent). example: 12.34 score_returned_from_customer: type: integer format: int64 description: >- Total amount of points that customer resturned to the company due to a product return. example: 12 score_returned_from_customer_as_money: type: number description: >- Total amount of discount money returned to the company in the cart (points equivalent). example: 12.34 shipment: type: array items: $ref: '#/components/schemas/shipment1' description: '' vouchers_desired: type: array deprecated: true description: >- **Use `coupons_desired` instead** 'Vouchers sent in the request are those the user intended to apply. If the request included "selected", this field will list all vouchers the customer selected and attempted to apply to the ticket. Note: This does not confirm the vouchers were successfully applied. To see which vouchers were actually applied, refer to the vouchers field.' coupons_desired: type: array description: >- 'Coupons sent in the request are those the user intended to apply. If the request included "selected", this field will list all coupons the customer selected and attempted to apply to the ticket. Note: This does not confirm the coupons were successfully applied. To see which vouchers were actually applied, refer to the vouchers field.' vouchers: type: array items: $ref: '#/components/schemas/VoucherActivityResponse' description: >- This attribute is returned exclusively when targeted campaign vouchers have been successfully applied to the purchase. total_discount_voucher_applied: type: number description: >- Total amount of discount money applied by targeted coupons within the cart example: 11.2 total_discount_promotion_applied: type: number description: Total amount of discount money applied by promotions within the cart example: 0 total_discount_applied: type: number description: >- Total amount of discount money applied by all discount campaigns within the cart example: 11.2 effects: type: array items: $ref: '#/components/schemas/Effects' description: > Only for new engine version. This section provides a comprehensive overview of all loyalty effects applied to the purchase, encompassing both points-earning and discount-based campaigns. example: - rule_id: 2322 line: 1 rule_name: Product Discount type: discount effect_type: percentage distribution_type: individual_items select_customers: loyalty value: 100 - rule_id: 2323 line: -1 rule_name: Holiday Points Bonus type: points effect_type: direct_value distribution_type: total select_customers: all_customers value: 600 value_as_money: 6 available_from: '2025-06-01' available_to: '2026-05-30' - rule_id: 2324 line: 2 rule_name: Combo Meal Deal type: discount effect_type: combo_price distribution_type: individual_items_pro_rata select_customers: targeted value: 400 coupon_info: voucher_id: 111 voucher_code: 4344fjaa coupon_id: 122211 coupon_name: Combo Meal Deal - rule_id: 2325 line: 3 rule_name: Cashback Offer type: points effect_type: ratio distribution_type: total select_customers: loyalty value: 600 value_as_money: 6 available_from: '2025-06-01' available_to: '2026-05-30' - type: discount rule_id: 23224 rule_name: Discount 15% promo distribution_type: individual_items select_customers: targeted effect_type: rollback line: 6 value: 400 coupon_info: voucher_id: 222 voucher_code: sale190 coupon_id: 12311 coupon_name: Sales discount example - type: points effect_type: rollback rule_id: 12313 rule_name: Double points promo Weekends distribution_type: individual_items select_customers: targeted line: 7 value: -200 coupon_info: voucher_id: 223 voucher_code: doublepoints coupon_id: 12312 coupon_name: Double points campaign rejected_campaigns: type: array items: $ref: '#/components/schemas/RejectedCampaign' description: >- Only for new engine version. This attribute lists all campaigns , vouchers or coupons that were attempted to be applied to the cart but were rejected, along with the reasons for their rejection. invalid_coupons: type: array description: >- Only for new engine version. This attribute contains a list of all vouchers or coupons specified in `coupons_desired` that are either invalid or do not exist attributes: type: object description: >- Attributes allow you to store additional data on activities. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true associate_id: type: integer format: int64 description: >- ID of the associated that created the cart, if the customer has associates. example: 101 cashbacks: type: array items: $ref: '#/components/schemas/cashbacks' description: cashbacks used in the cart if applies total_net: type: number description: Total amount of the cart if provided on creation. example: 120 total_tax: type: number description: Total tax of the cart if provided on creation. example: 12 custom1: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 1 of the cart. example: '100' custom2: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 2 of the cart. example: '100' custom3: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 3 of the cart. example: '100' custom4: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 4 of the cart. example: '100' custom5: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 5 of the cart. example: '100' custom6: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 6 of the cart. example: '100' custom7: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 7 of the cart. example: '100' custom8: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 8 of the cart. example: '100' order_id: type: integer format: int64 description: ID of the order. example: 100 score_simulation: type: boolean deprecated: true description: >- Show to a non-registered customer the amount of points that would be won. example: true returns: type: array items: $ref: '#/components/schemas/returns' description: returns used in the cart if applies cashback_returns: type: array items: $ref: '#/components/schemas/cashback_returns1' description: cashback returns used in the cart if applies promotions: type: array deprecated: true items: $ref: '#/components/schemas/PromotionV3' description: >- This is only an informative field, you can't apply a promotion through this field. cashback_score_desired: type: number description: >- Total amount of points that the customer wanted to spend in the cart. example: 12 cashback_score_desired_unused: type: number description: >- Total amount of points that were not used related to the desired amount. example: 12 checkout_date: type: string description: DateTime of the checkout of the cart. example: '2016-01-01T23:43:20Z' payment_cost: type: number description: Total amount of payment cost paid by the customer. example: 1.5 shipping_cost: type: number description: Total amount of shipping cost paid by the customer. example: 5.5 channel: type: string description: Channel from which the cart comes. example: online tpv_id: type: string description: ID of TPV. example: '100' staff_name: type: string description: Name of the staff. example: '120' staff_code: type: string description: Code of the staff. example: '12' Getanactivityresponse1: title: Getanactivityresponse1 type: object properties: error: type: string example: error: Internal server error Promotions1: title: Promotions1 required: - promotion_id - product_id - discount - line_order - discount_int type: object properties: promotion_id: type: integer format: int64 product_id: type: integer format: int64 discount: type: number line_order: type: integer format: int64 discount_int: type: integer format: int64 example: promotion_id: 11 product_id: 34 discount: 4.1 line_order: 5 discount_int: 4 Payments1: title: Payments1 required: - amount - type - change type: object properties: amount: type: integer format: int64 type: type: string change: type: number example: amount: 20 type: cash change: 4.25 Cashbacks1: title: Cashbacks1 required: - line_order - score - discount type: object properties: line_order: type: integer format: int64 score: type: integer format: int64 discount: type: number example: line_order: 1 score: 100 discount: 8.5 CashbackReturns2: title: CashbackReturns2 required: - line_order - score type: object properties: line_order: type: integer format: int64 score: type: integer format: int64 example: line_order: 1 score: 10 Returns1: title: Returns1 required: - line_order - quantity - ticket_id - ticket_code - from_line_order - score type: object properties: line_order: type: integer format: int64 quantity: type: number ticket_id: type: integer format: int64 ticket_code: type: string from_line_order: type: integer format: int64 score: type: integer format: int64 example: line_order: 2 quantity: 5.3 ticket_id: 12 ticket_code: a1b2c3d4 from_line_order: 1 score: 10 Line1: title: Line1 required: - order - total - total_net - total_tax - total_cost - original_total - price - quantity - product_code - product_ean - product_id - product_name - product_tax - custom1 - custom2 - custom3 - custom4 - custom5 - custom6 - custom7 - custom9 type: object properties: order: type: integer format: int64 total: type: number total_net: type: integer format: int64 total_tax: type: number total_cost: type: integer format: int64 original_total: type: integer format: int64 price: type: integer format: int64 quantity: type: integer format: int64 product_code: type: string product_ean: type: string product_id: type: integer format: int64 product_name: type: string product_tax: type: integer format: int64 custom1: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 1 of activity line. custom2: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 2 of activity line. custom3: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 3 of activity line. custom4: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 4 of activity line. custom5: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 5 of activity line. custom6: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 6 of activity line. custom7: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 7 of activity line. custom9: type: string deprecated: true description: |- **Use `attributes` instead** Custom field 9 of activity line. attributes: type: object description: >- Attributes allow you to store additional data on activity lines. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true example: order: 1 total: 15.75 total_net: 14 total_tax: 1.75 total_cost: 16 original_total: 16 price: 16 quantity: 3 product_code: PR00987L product_ean: GHT567A product_id: 987 product_name: Product 987 1L product_tax: 21 custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom9: custom 9 value attributes: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true StatusHistories1: title: StatusHistories1 required: - status - created_at type: object properties: status: type: string created_at: type: string example: status: first_status created_at: '2017-12-25T23:45:55Z' Shipment2: title: Shipment2 required: - status - tracking_code - delivery_address - company - tracking_url - status_histories type: object properties: status: type: string tracking_code: type: string delivery_address: type: string company: type: string tracking_url: type: string status_histories: type: array items: $ref: '#/components/schemas/StatusHistories1' description: '' example: status: some_status tracking_code: some_code delivery_address: some-address company: some-company tracking_url: some-url status_histories: - status: first_status created_at: '2017-12-25T23:45:55Z' - status: second_status created_at: '2017-12-28T23:45:55Z' RewardCategory: title: RewardCategory type: object nullable: true description: Categories list of the reward properties: id: description: The ID of the category. type: integer format: int64 name: description: The name of the category. type: string taxonomy_slug: description: The slug of the taxonomy related to the category type: string image_url: description: The link of the image related with the category type: string example: id: 3 name: Football taxonomy_slug: sports image_url: null Partner: title: Partner type: object nullable: true properties: id: description: The ID of the partner type: integer format: int64 name: description: The name of the partner type: string description: description: The description of the partner type: string image_url: description: The link of the image related with the partner type: string image_file_name: description: The file name of the image related with the partner type: string example: id: 1 name: Airlines LG description: partnership with airline image_url: https//www.imagetest.com/image.png image_file_name: image.png Reward: title: Reward type: object properties: id: description: The ID of the reward. type: integer example: 1001 name: description: >- The name of the reward. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. type: string example: Reward name description: description: >- The description of the reward. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. type: string points: type: integer description: The necessary points required to redeem the reward. example: 150 available_from: description: The date at which this reward will be available. type: string format: date example: '2019-02-01' available_to: description: The date until which this reward will be available. type: string format: date example: '2020-02-01' flexible_score_allowed: description: A flag indicating if the reward allows the score to be overwritten. type: boolean status: description: The status of the reward (active or inactive). type: string example: active countries: description: The countries in which this reward is available. type: array items: type: string extra_money: description: Extra money needed to redeem the reward. type: number format: float currency: description: >- The currency with which the reward must be redeemed. Must be in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) format. Must be present if extra_money is provided. type: string is_coupon: description: A flag indicating if the reward is a coupon. type: boolean image_url: description: The image (thumbnail) link of the reward. type: string image_file_name: description: The image (thumbnail) file name of the reward. type: string categories: type: array items: $ref: '#/components/schemas/RewardCategory' coupon: $ref: '#/components/schemas/Coupon' nullable: true type: description: Type name of the reward type: string example: physical partner: description: The partner related to the reward nullable: true $ref: '#/components/schemas/Partner' redeem_chances: description: >- Define limitations regarding how many times this reward can be redeemed per customer. Options: - "always" - Unlimited redemptions quantity per customer - "num_total" - Total number of times - "num_day" - Total of times per day (natural) - "num_month" - Total of times per month - "num_year" - Total of times per year type: string redeem_times: description: >- Define limitations regarding how many times this reward can be redeemed per customer. Its related to the value defined in redeemed_chances. - if redeem_chances = "always" this field is not considered - E.g.: If redeem_times = 8 and redeem_chances = "num_year" it means the same customer may redeem this reward 8 times per year maximum type: integer validity_duration_number: description: >- Number that defines the validity of the reward after redemption. Available when validity_duration_type = 'relative'. type: integer example: 3 validity_duration_unit_option: description: >- Unit that defines the validity of the reward after redemption. Available when validity_duration_type = 'relative'. Options are "days", "months", "years". type: string example: months validity_duration_date: description: >- Date that defines the validity of the reward after redemption. Available when validity_duration_type = 'fixed'. type: string example: '2024-02-01' validity_duration_type: description: >- Type to define validity of the reward. It can be 'fixed' or 'relative'. type: string example: fixed Datum1: title: Datum1 required: - id - code - barcode - creation_date - customer_id - associate_id - location_id - total - international - score - score_used - score_returned_from_customer - score_returned_to_customer - business_name - total_net - total_tax - tpv_id - staff_name - staff_code - currency - score_simulation - cashback_score_desired - cashback_score_desired_unused - custom1 - custom2 - custom3 - custom4 - custom5 - custom6 - custom7 - custom8 - promotions - customer - payments - cashbacks - scores - cashback_returns - returns - lines - shipment - rewards type: object properties: id: type: integer format: int64 code: type: string barcode: type: string creation_date: type: string customer_id: type: integer format: int64 associate_id: type: integer format: int64 location_id: type: integer format: int64 total: type: number international: type: boolean score: type: integer format: int64 score_used: type: integer format: int64 score_returned_from_customer: type: integer format: int64 score_returned_to_customer: type: integer format: int64 business_name: type: string total_net: type: integer format: int64 total_tax: type: number format: float tpv_id: type: string staff_name: type: string staff_code: type: string currency: type: string score_simulation: type: boolean cashback_score_desired: type: integer format: int64 cashback_score_desired_unused: type: integer format: int64 custom1: type: string custom2: type: string custom3: type: string custom4: type: string custom5: type: string custom6: type: string custom7: type: string custom8: type: string promotions: type: array items: $ref: '#/components/schemas/Promotions1' description: '' customer: $ref: '#/components/schemas/Customer' payments: type: array items: $ref: '#/components/schemas/Payments1' description: '' cashbacks: type: array items: $ref: '#/components/schemas/Cashbacks1' description: '' scores: type: array items: $ref: '#/components/schemas/Scores1' description: '' cashback_returns: type: array items: $ref: '#/components/schemas/CashbackReturns2' description: '' returns: type: array items: $ref: '#/components/schemas/Returns1' description: '' lines: type: array items: $ref: '#/components/schemas/Line1' description: '' shipment: $ref: '#/components/schemas/Shipment2' rewards: type: array items: $ref: '#/components/schemas/Reward' description: '' attributes: type: object description: >- Attributes allow you to store additional data on activities. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true example: id: 1234 code: T1234 barcode: '0012349437' creation_date: '2017-10-16T12:45:55Z' customer_id: 99302 associate_id: 99303 location_id: 43 total: 15.75 international: true score: 100 score_used: -20 score_returned_from_customer: -20 score_returned_to_customer: 40 business_name: Streaming Corp total_net: 14 total_tax: 1.75 tpv_id: AT123 staff_name: John Doe staff_code: john-doe currency: EUR score_simulation: true cashback_score_desired: 10 cashback_score_desired_unused: 8 custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom8: custom 8 value promotions: - promotion_id: 11 product_id: 34 discount: 4.1 line_order: 5 discount_int: 4 customer: id: 99302 code: 99302a score: 10 score_available: 10 payments: - amount: 20 type: cash change: 4.25 cashbacks: - line_order: 1 score: 100 discount: 8.5 scores: - line_order: 1 score: 100 loyalty_score_id: 2 available_from: '2016-01-01' cashback_returns: - line_order: 1 score: 10 returns: - line_order: 2 quantity: 5.3 ticket_id: 12 ticket_code: a1b2c3d4 from_line_order: 1 score: 10 lines: - order: 1 total: 15.75 total_net: 14 total_tax: 1.75 total_cost: 16 original_total: 16 price: 16 quantity: 3 product_code: PR00987L product_ean: GHT567A product_id: 987 product_name: Product 987 1L product_tax: 21 custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom9: custom 9 value shipment: status: some_status tracking_code: some_code delivery_address: some-address company: some-company tracking_url: some-url status_histories: - status: first_status created_at: '2017-12-25T23:45:55Z' - status: second_status created_at: '2017-12-28T23:45:55Z' rewards: - id: 319 discount: 3.2 line_order: 2 product_id: 12 attributes: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true Getalistofactivitiesresponse: title: Getalistofactivitiesresponse required: - data - next_token_starts_after type: object properties: data: type: array items: $ref: '#/components/schemas/Datum1' description: '' next_token_starts_after: type: string example: data: - id: 1234 code: T1234 barcode: '0012349437' creation_date: '2017-10-16T12:45:55Z' customer_id: 99302 associate_id: 99303 location_id: 43 total: 15.75 international: true score: 100 score_used: -20 score_returned_from_customer: -20 score_returned_to_customer: 40 business_name: Streaming Corp total_net: 14 total_tax: 1.75 tpv_id: AT123 staff_name: John Doe staff_code: john-doe currency: EUR score_simulation: true cashback_score_desired: 10 cashback_score_desired_unused: 8 custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom8: custom 8 value promotions: - promotion_id: 11 product_id: 34 discount: 4.1 line_order: 5 discount_int: 4 customer: id: 99302 code: 99302a score: 10 score_available: 10 payments: - amount: 20 type: cash change: 4.25 cashbacks: - line_order: 1 score: 100 discount: 8.5 scores: - line_order: 1 score: 100 loyalty_score_id: 2 available_from: '2016-01-01' cashback_returns: - line_order: 1 score: 10 returns: - line_order: 2 quantity: 5.3 ticket_id: 12 ticket_code: a1b2c3d4 from_line_order: 1 score: 10 lines: - order: 1 total: 15.75 total_net: 14 total_tax: 1.75 total_cost: 16 original_total: 16 price: 16 quantity: 3 product_code: PR00987L product_ean: GHT567A product_id: 987 product_name: Product 987 1L product_tax: 21 custom1: custom 1 value custom2: custom 2 value custom3: custom 3 value custom4: custom 4 value custom5: custom 5 value custom6: custom 6 value custom7: custom 7 value custom9: custom 9 value shipment: status: some_status tracking_code: some_code delivery_address: some-address company: some-company tracking_url: some-url status_histories: - status: first_status created_at: '2017-12-25T23:45:55Z' - status: second_status created_at: '2017-12-28T23:45:55Z' rewards: - id: 319 discount: 3.2 line_order: 2 product_id: 12 attributes: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true next_token_starts_after: token Getalistofactivitiesresponse1: title: Getalistofactivitiesresponse1 required: - error type: object properties: error: type: string example: error: Internal server error CancelACartRequest: title: CancelACartRequest required: - cart_to_cancel_id - cart_to_cancel_code - new_cart_id - new_cart_code type: object properties: cart_to_cancel_id: type: integer format: int64 description: >- Id of the cart to cancel. `cart_to_cancel_id` OR `cart_to_cancel_code` are **required** and mutually exclusive. example: 2122322222 cart_to_cancel_code: type: string description: >- Code of the cart to cancel. `cart_to_cancel_id` OR `cart_to_cancel_code` are **required** and mutually exclusive. example: AAHY79212 new_cart_id: type: integer format: int64 description: >- Id of the new cart that is going to be created for the full return. `new_cart_id` OR `new_cart_code` are **required** and mutually exclusive.' example: 822323232 new_cart_code: type: string format: int64 description: >- Code of the new cart that is going to be created for the full return. `new_cart_id` OR `new_cart_code` are **required** and mutually exclusive.' example: 8223a CancelACartResponse: title: CancelACartResponse type: object properties: id: type: integer format: int64 description: ID of the return cart in form of an integer. example: 1234 code: type: string description: 'Identification `code` of the return cart in form of an string. ' example: 1a2b3c4d location_id: type: integer format: int64 description: ID of the location in form of an integer. example: 12 location_code: type: string description: Code of the location. example: 12A customer_id: type: integer format: int64 description: ID of the customer in form of an integer. example: 8223 customer_code: type: string description: Alphanumeric customer code. example: 8223a creation_date: type: string description: DateTime of the creation of the cart. example: '2022-01-01T23:43:20Z' total: type: number description: >- Total amount of the purchase cart payed by the customer. If the cart is a cancellation this amount should be negative. example: -100 currency: type: string description: Code of the currency acording to the [ISO 4217] example: EUR customer: type: array items: $ref: '#/components/schemas/Customer' description: > Provides supplementary information about the customer, relevant to the current purchase, only if the customer is identified in the transaction. score: type: integer format: int64 description: Total amount of points win in a cart by all points campaigns example: 100 score_as_money: type: number description: >- Total amount of discount money won in this cart by all points campaigns example: 12.65 score_used: type: integer format: int64 description: Total amount of points used in a cart. example: 120 score_used_as_money: type: number description: Total amount of discount money (by points burned) used in a cart. example: 12.65 score_returned_from_customer: type: integer format: int64 description: Total amount of points that customer lost in a return. example: 12 score_returned_from_customer_as_money: type: number description: >- Total amount of discount money (considering points) that customer lost in a return. example: 1.25 score_returned_to_customer: type: integer format: int64 description: Total amount of points that customer win in a return. example: 12 score_returned_to_customer_as_money: type: number description: >- Total amount of discount money that customer win in a return by points returned. example: 1.25 total_scores_coupon_applied: type: number description: Total amount of scores won by coupons within the cart example: 116 total_scores_coupon_applied_as_money: type: number description: >- Total amount of money won by points coupons within the cart (total_scores_coupon_applied money equivalent) example: 1.16 total_discount_voucher_applied: type: number description: >- Total amount of discount money applied by targeted coupons within the cart example: 11.2 total_discount_applied: type: number description: >- Total amount of discount money applied by all discount campaigns within the cart example: 11.2 lines: type: array items: $ref: '#/components/schemas/LineActivity' description: | Array of lines. **Important** + The **`total`** amount of returned lines on the cart is adjusted after applying all relevant discounts, including those from promotional campaigns, vouchers, and any point-based discounts (cashback). + The original, unadjusted amount for each line item remains unchanged and is preserved in the **`original_total`** attribute. returns: type: array items: $ref: '#/components/schemas/Return' description: Array of returns line by line effects: type: array items: $ref: '#/components/schemas/Effects' description: > This section provides a comprehensive overview of all loyalty effects applied to the purchase, encompassing both points-earning and discount-based campaigns. example: - type: discount effect_type: rollback rule_id: 54321 rule_name: Summer Sale 20% Off distribution_type: total_cart select_customers": targeted value: -15 coupon_info: voucher_id: 456 voucher_code: SUMMER20 coupon_id: 65432 coupon_name: Summer Sale Campaign - type: points effect_type: rollback rule_id: 12313 rule_name: Double points promo Weekends distribution_type: individual_items select_customers": targeted line: 7 value: -200 coupon_info: voucher_id: 223 voucher_code: doublepoints coupon_id: 12312 coupon_name: Double points campaign cashback_returns: type: array items: $ref: '#/components/schemas/Cashback_returns' description: > This attribute is present when the cart involves returned items. It visualizes all points that were originally redeemed (used for discounts) in the initial purchase and are now being returned to the customer as part of the return transaction. coupons_desired: type: array description: >- 'Coupons sent in the request are those the user intended to apply. If the request included "selected", this field will list all coupons the customer selected and attempted to apply to the ticket. Note: This does not confirm the coupons were successfully applied. To see which coupons were actually applied, refer to the vouchers field.' attributes: type: object description: Attributes allow you to store additional data on activities. example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true ScoreSummary: title: ScoreSummary type: object properties: score: type: integer format: int64 loyalty_score_id: type: integer format: int64 available_from: type: string available_to: type: string customer1: title: customer1 type: object properties: id: type: integer format: int64 description: ID of the customer. example: 12 code: type: string description: Code of the customer. example: 12a score: type: integer format: int64 description: Total amount of points of the customer. example: 100 score_available: type: integer format: int64 description: Total amount of available points of the customer. example: 100 CustomEntityResponse: title: CustomEntityCreateResponse type: object properties: id: type: string description: Custom entity identifier. customer_id: type: integer description: The numerical identifier of the owner customer. customer_code: type: string description: The alphanumeric identifier of the owner customer. slug: type: string description: Custom entity definition identifier. data: type: object description: >- Custom entity payload. It will be validated against the schema configured for the definition with the provided slug. created_at: type: string description: Custom entity date of creation. ingested_at: type: string description: Custom entity date of ingestion. score: type: integer description: Total score generated by the ingestion of the custom entity. score_available: type: integer description: >- Total available score generated by the ingestion of the custom entity. scores: type: array items: $ref: '#/components/schemas/ScoreSummary' description: List of scores generated by the ingestion of the custom entity. customer: $ref: '#/components/schemas/customer1' CustomEntityListResponse: title: Getalistofcustomentitiesresponse required: - data - next_token_starts_after type: object properties: data: type: array items: $ref: '#/components/schemas/CustomEntityResponse' description: '' next_token_starts_after: type: string CustomEntityCreateRequest: title: CustomEntityCreateRequest required: - slug - data type: object properties: id: type: string description: Custom entity identifier. **It must be unique**. customer_id: type: integer description: >- The numerical identifier of the owner customer. Required if customer_code is not provided. customer_code: type: string description: >- The alphanumeric identifier of the owner customer. Required if customer_id is not provided. slug: type: string description: Custom entity definition identifier. data: type: object description: >- Custom entity payload. It will be validated against the schema configured for the definition with the provided slug. created_at: type: string description: Custom entity date of creation. TriggerRequestCustomerID: title: Trigger request with customer_id required: - customer_id - trigger - loyalty_rule_id type: object properties: trigger: type: string description: >- Slug of the trigger associated to the points campaign. `trigger` or `loyalty_rule_id` are **required** and might be used together. It is **recommended** to always use `loyalty_rule_id` if you want only one rule to be applied. example: manual_adjustment customer_id: type: number description: ID of the customer. Mutually exclusive with `customer_code`. example: 10 loyalty_score_id: type: integer deprecated: true format: int64 description: >- Id of the loyalty rule that you would like to trigger. Use `loyalty_rule_id` instead. `trigger` or `loyalty_score_id` are **required** and might be used together. example: 12 loyalty_rule_id: type: integer format: int64 description: >- Id of the points campaign that you would like to trigger. `trigger` or `loyalty_rule_id` are **required** and might be used together. It is **recommended** to always use `loyalty_rule_id` if you want only one rule to be applied, otherwise all associated campaigns will be executed. example: 12 location_id: type: number description: >- Id of the trigger location. `location_id` or `location_code` are mutually exclusive. example: 1 location_code: type: string description: >- Code of the trigger location. `location_id` or `location_code` are mutually exclusive. example: 12A score_overwrite: type: number description: >- Overwrite the score given by the campaign. **Only makes sense if loyalty_rule_id is provided.** If no value, points associated to the campaign will be given. Maximum value allowed: 50000000' example: 30 comments: type: string description: Comments about the trigger transaction. example: 30 extra points for completing the poll country: type: string description: >- [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (It must be Capitals letters **Required for Version 1 engine.** For Version 2 engine, if not provided, the customer's registration location country will be used. example: ES TriggerRequestCustomerCode: title: Trigger request with customer_code required: - customer_code - trigger - loyalty_rule_id type: object properties: trigger: type: string description: >- Slug of the trigger associated to the points campaign. `trigger` or `loyalty_rule_id` are **required** and might be used together. It is **recommended** to always use `loyalty_rule_id` if you want only one rule to be applied. example: manual_adjustment customer_code: description: The customer's code. Mutually exclusive with `customer_id` type: string example: a1b2c3d4 loyalty_score_id: type: integer deprecated: true format: int64 description: >- Id of the loyalty rule that you would like to trigger. Use `loyalty_rule_id` instead. `trigger` or `loyalty_score_id` are **required** and might be used together. example: 12 loyalty_rule_id: type: integer format: int64 description: >- Id of the points campaign that you would like to trigger. `trigger` or `loyalty_rule_id` are **required** and might be used together. It is **recommended** to always use `loyalty_rule_id` if you want only one rule to be applied, otherwise all associated campaigns will be executed. example: 12 location_id: type: number description: >- Id of the trigger location. `location_id` or `location_code` are mutually exclusive. example: 1 location_code: type: string description: >- Code of the trigger location. `location_id` or `location_code` are mutually exclusive. example: 12A score_overwrite: type: number description: >- Overwrite the score given by the campaign. **Only makes sense if loyalty_rule_id is provided.** If no value, points associated to the campaign will be given. Maximum value allowed: 50000000' example: 30 comments: type: string description: Comments about the trigger transaction. example: 30 extra points for completing the poll country: type: string description: >- [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (It must be Capitals letters **Required for Version 1 engine.** For Version 2 engine, if not provided, the customer's registration location country will be used. example: ES EffectsTriggerResponse: title: EffectsTriggerResponse type: object properties: rule_id: description: The ID of the promotion campaign. type: integer example: 2322 rule_name: description: The name of the promotion campaign. type: string example: Birthday Points type: description: 'Type of the promotion campaign. Options: "points"' type: string example: discount effect_type: type: string description: >- Type of the effect applied. Possible options: **Direct Value Strategy** - **Key:** `direct_value` - Applies a fixed monetary or point value. - **Value (decimal, > 0):** The fixed amount to apply. - Awards a fixed number of points (e.g., a value of `100` awards 100 points). example: percentage distribution_type: description: >- The only distribution type available for triggers is `total`, which means that the effect is applied to the entire transaction. type: string example: total select_customers: description: >- Determines the **customer segment** to which this rule applies. This allows you to specify whether the rule is valid for: + **Loyalty Members (`loyalty`):** Only customers actively enrolled in a loyalty program. + **Targeted Customers (`targeted`):** A specific subset of customers identified through particular criteria (e.g., via a segment). type: string example: loyalty value: description: the value of points given by the effect. type: number example: 20 value_as_money: description: >- when points: The money equivalence of points based on the score exchange value for the currency (in cents) type: number example: 2000 available_from: description: Date when earned points become available for use type: number example: '2025-01-02' available_to: description: Date when earned points expire type: number example: '2025-08-02' TriggerResponse: title: TriggerResponse type: object properties: customer_code: description: The customer_code of the customer if present type: string deprecated: true loyalty_score_id: description: >- The ID of the loyalty score rule/policy that was triggered (if loyalty_rule_id included in the request, this will be the same as loyalty_rule_id) type: integer format: int64 example: 12 score: description: Total points granted to the customer by the trigger type: integer format: int64 example: 110 score_as_money: type: number format: float description: >- The equivalent value of the score in the currency of the loyalty program example: 11 customer: $ref: '#/components/schemas/customer1' scores: type: array deprecated: true items: $ref: '#/components/schemas/Scores1' example: - loyalty_score_id: 2222 score: 100 available_from: '2025-06-01' available_to: '2026-05-30' - loyalty_score_id: 1222 score: 10 available_from: '2025-06-01' available_to: '2026-05-30' effects: type: array items: $ref: '#/components/schemas/EffectsTriggerResponse' description: >- List of detailed effects produced by the trigger (one per loyalty rule executed). For engine version2 example: - rule_id: 2222 rule_name: Manual points adjustment type: points effect_type: direct_value distribution_type: total select_customers: loyalty value: 100 value_as_money: 10 available_from: '2025-06-01' available_to: '2026-05-30' - rule_id: 1222 rule_name: Manual extra points for tier Gold type: points effect_type: direct_value distribution_type: total select_customers: loyalty value: 10 value_as_money: 1 available_from: '2025-06-01' available_to: '2026-05-30' TriggerResponseError: title: TriggerResponseError type: object properties: code: type: string error: type: string CategoryCampaign: title: CategoryCampaign type: object nullable: true properties: id: description: The ID of the category type: integer format: int64 name: description: The name of the category type: string priority: description: The priority of the category type: integer example: id: 1 name: Baseline priority: 1 AchievementDefinitionResponse: title: AchievementDefinitionResponse type: object properties: id: type: integer format: int64 description: Achievement definition ID example: 132 level: type: integer format: int32 description: Level of the achievement example: 2 name: type: string description: Name of the achievement example: Silver tier_id: type: integer format: int64 description: ID of the tier associated with the achievement example: 122 tier_name: type: string description: Name of the tier associated with the achievement example: Total expenditure VoucherInfo: title: VoucherInfo nullable: true type: object properties: voucher_id: type: integer description: The ID of the voucher. voucher_code: type: string description: The code of the voucher. available_redemptions: type: integer description: >- The number of available redemptions for the voucher and the specific customer max_redemptions: type: integer description: >- The maximum number of redemptions for the voucher originally set for the campaign selected: type: boolean description: Indicates if the voucher is selected status: type: string description: The status of the voucher available_from: type: string format: date-time description: The date and time from which the voucher is available. available_to: type: string format: date-time description: The date and time until which the voucher is available. print_from: type: string format: date-time description: The date and time from which the voucher can be printed. print_to: type: string format: date-time description: The date and time until which the voucher can be printed. priority: type: integer description: The priority of the voucher. printable: type: boolean description: >- Indicates if the voucher is printable. Avoid print_from and print_to fields if this value is false CouponInfoCampaignResponse: title: CouponInfoCampaignResponse nullable: true type: object properties: coupon_id: description: The ID of the coupon. type: integer format: int64 static_code: description: The static code of the coupon. type: string coupon_name: type: string example: Discount meat 50% description: Name of the coupon external_id: description: The external ID of the coupon. type: string key: description: The key of the coupon. type: string voucher_info: description: The information about the voucher associated with this coupon. $ref: '#/components/schemas/VoucherInfo' example: coupon_id: 123 static_code: SALE50OFF coupon_name: ' Discount meat 50%' external_id: EXT-456 key: VOUCHER123 voucher_info: voucher_id: 789 voucher_code: SALE50OFF available_redemptions: 10 max_redemptions: 100 selected: true status: pending available_from: '2024-01-01T00:00:00Z' available_to: '2024-12-31T23:59:59Z' print_from: '2024-01-01T00:00:00Z' print_to: '2024-12-31T23:59:59Z' priority: 1 printable: true DiscountResponse: title: DiscountResponse type: object properties: id: description: >- The ID of the campaign for loyalty or all_members campaigns. For targeted campaigns it returns the id of the loyalty rule history. type: integer example: 1001 name: description: >- Name of the loyalty campaign. Can be a string or a hash for multi-language names. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. type: string example: 25 % discount on selected category description: description: >- The description of the loyalty campaign. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. type: string category: description: Category of the discount campaign nullable: true $ref: '#/components/schemas/CategoryCampaign' active: type: boolean description: Indicates if the campaign is active. example: true available_from: type: string format: date description: The date from which the campaign is active (YYYY-MM-DD). example: '2025-06-01' available_to: type: string format: date description: The date until which the campaign is active (YYYY-MM-DD). example: '2025-12-31' recurrence_type: type: string description: Type of recurrence for the campaign. enum: - daily - monthly_last - weekly - monthly default: daily example: daily recurrence_days: type: array description: >- Specific days for recurrence. For weekly: 0-6 (Sunday-Saturday). For monthly: 1-31. Empty for daily and monthly_last. items: type: integer currency: type: string description: Campaign Currency. Currency in which this campaign runs (iso-code) example: EUR coupon_required: type: boolean description: >- Indicates if a coupon is required to apply the campaign. If this value is true, the promotion provided by this campaign can only be used by presenting a coupon (or by deliberately activating it through an interface) **Must be true if the campaign is targeted** example: false when: type: string description: > Trigger or event that activates the campaign. Options: - `after_create_activity`: This is a general event triggered after a purchase is done. The campaign tied to this event would typically reward points or benefits based on the activity completed. Examples include: - Offering bonus discounts for purchasing specific products or categories. - Providing a discount code for future purchases after a certain spending threshold is met. example: after_create_activity select_customers: type: string description: |- Defines the target audience for the campaign. Options are: - `all_customers` fom massive campaigns - `loyalty` for loyalty members campaigns - `targeted` for specific customers or segments example: loyalty customer_registration_countries: type: array description: >- Countries in which the customer must be registered for campaign eligibility items: type: string achievement_definitions: description: Tiers customers need to reach to qualify for the campaign type: array items: $ref: '#/components/schemas/AchievementDefinitionResponse' rule_conditions: description: > Advanced campaign conditions, represented as a JSON object. These conditions defines complex eligibility conditions for campaigns, combining logical operators (`and`, `or`) with different fields such as cart totals, country, payment methods, store locations, product IDs, product categories, and custom attributes. ### Supported fields and operators - **Numbers** (`total`, `quantity`, `total_net`): operators include `gte`, `lte`, `eq`, etc. - **Country** (`country`): operator `in`, values are ISO codes. - **Payment methods** (`payment_method`): operator `in`, values are slugs of payment types (e.g., `card`, `cash`). - **Stores** (`location_id`): operator `in`, values are store IDs. - **Store categories** (`location_categories`): operator `in`, values are category IDs. - **Products** (`product_id`, `product_categories`): operator `in`, values are IDs or external IDs. - **Cart Item attributes** (`custom1`, `custom5`, etc.): operators like `eq`. - **Nested conditions**: support combining conditions with quantity or total validations inside product lines. ### Example ```json { "conditions": { "and": [ { "field": "total", "operator": "gte", "value": 100, "key": "cart.total" }, { "field": "country", "operator": "in", "values": ["ES","UY","AR"], "key": "cart.country" }, { "array_field": "payments", "field": "type", "operator": "in", "values": ["card","cash","U","V","debit_card"], "key": "cart.payment_method" }, { "field": "location_id", "operator": "in", "values": [1,2,3,4], "key": "cart.location_id" }, { "field": "location_categories", "operator": "in", "values": [3,4,2,1], "key": "cart.location_feature" }, { "array_field": "lines", "field": "product_id", "key": "cart.item.product", "bundle": "2", "operator": "in", "values": [1], "grouped": true, "conditions": [ { "field": "quantity", "operator": "gte", "value": 2 }, { "field": "total", "operator": "gte", "value": 200 } ] }, { "array_field": "lines", "field": "product_categories", "key": "cart.item.product_categories", "bundle": "2", "operator": "in", "values": [45454] }, { "array_field": "lines", "field": "product_categories", "key": "cart.item.product_category", "operator": "in", "values": [2, 43, 232], "grouped": true, "conditions": [ { "field": "total", "operator": "gte", "value": 150 } ] } ] } } ``` example: >- {"conditions": {"and": [{"key": "cart_product_id", "field": "product_id", "bundle": 1, "values": [5], "grouped": true, "operator": "in", "conditions": [{"field": "quantity", "value": 1, "operator": "eq"}], "array_field": "lines"}]}} rule_application: type: string description: > Advanced campaign application logic (JSON object). This field defines how the campaign is applied to the cart, specifying which items or conditions must be met for the discount to take effect. It uses a similar structure to `rule_conditions`, allowing for complex rules based on product IDs, categories, quantities, and other attributes. ### Example ```json { "application": { "and": [ { "array_field": "lines", "field": "product_id", "key": "cart.item.product", "bundle": "1", "operator": "in", "values": [5], "grouped": true, "conditions": [ { "field": "quantity", "operator": "eq", "value": 1 } ] } ] } } ``` example: >- {"application": {"and": [{"key": "cart_product_id", "field": "product_id", "bundle": 1, "values": [5], "grouped": true, "operator": "in", "conditions": [{"field": "quantity", "value": 1, "operator": "eq"}], "array_field": "lines"}]}} rule_effects: type: string description: | Advanced campaign effects (JSON object). Supported effect types include: - **percentage** → applies a discount percentage on ticket/cart lines. - **direct_value** → fixed amount of discountapplied. - **ratio** → Every x monetary unit you get a x discount (e.g. for every 20 euros spent in Beverage you get €1 of discount). - **strikethrough** → replaces product final price by discounted price (unit-based). - **combo_price** → sets a final price for a group of products (e.g. 2x1, 3x2, packs). - **informative** → no monetary effect; displays an informational message. Distribution modes supported: - `total` → applies to total ticket. - `individual_items` → applies to each impacted line individually. - `individual_items_pro_rata` → prorates total effect across impacted lines. ### Example ```json { "key": "percentage", "type": "percentage", "value": 25, "distribution": "individual_items" } ``` example: >- {"key": "percentage", "type": "percentage", "value": 25, "distribution": "individual_items" } once: type: string description: >- Defines how many times a customer can win the specified discount campaign. Possible values are: - **always** : No limit on the number of times a customer can win. - **num_year** - Number of times per year (relative year): Limit based on the last 12 months. Example: if `current_date = 2024-12-22`, the validation period is `2023-12-23 to 2024-12-22`. - **num_month** - Number of times per month (relative month): Limit based on the last full month. Example: if `current_date = 2024-12-22`, the validation period is `2024-11-24 to 2024-12-22`. - **num_year_natural** - Number of times per year (natural year): Limit within the current calendar year. Example: if `current_date = 2024-12-22`, the validation period is `2024-01-01 to 2024-12-31`. - **num_month_natural** - Number of times per month (natural month): Limit within the current calendar month. Example: if `current_date = 2024-12-22`, the validation period is `2024-12-01 to 2024-12-31`. - **num_day** - Number of times per natural day: Limit within a natural day (from 00:00 to 23:59). - **num_total** - Total number of times: Limit across all history, without date restriction. enum: - num_day - num_month - num_year - always - num_total example: num_month once_limit: type: integer description: >- The limit for once parameter. If once is 'always', this value will be ignored. example: 1 chances_to_accrue_period: type: string description: >- Defines how many times in total (considering all customers) the specified discount campaign may apply. Possible values are: - **always** : No limit on the number of times a customer can win. - **num_year** - Number of times per year (relative year): Limit based on the last 12 months. Example: if `current_date = 2024-12-22`, the validation period is `2023-12-23 to 2024-12-22`. - **num_month** - Number of times per month (relative month): Limit based on the last full month. Example: if `current_date = 2024-12-22`, the validation period is `2024-11-24 to 2024-12-22`. - **num_year_natural** - Number of times per year (natural year): Limit within the current calendar year. Example: if `current_date = 2024-12-22`, the validation period is `2024-01-01 to 2024-12-31`. - **num_month_natural** - Number of times per month (natural month): Limit within the current calendar month. Example: if `current_date = 2024-12-22`, the validation period is `2024-12-01 to 2024-12-31`. - **num_day** - Number of times per natural day: Limit within a natural day (from 00:00 to 23:59). - **num_total** - Total number of times: Limit across all history, without date restriction. enum: - num_day - num_month - num_year - always - num_total example: num_month chances_to_accrue_limit: type: integer description: >- The limit for chances_to_accrue_period parameter. If once is 'always', this value will be ignored. example: 1 budget_value: type: integer description: >- Maximum budget limit for this campaign. The limit is specified in the company's default currency. if budget_period is "Unlimited", this value will be ignored. minimum: 1 example: 100000 budget_period: type: string description: >- Period for budget calculation. Empty if unlimited. - **unlimited or empty** : No limit on the budget. - **num_year** - Budget defined per year (relative year): Limit based on the last 12 months. Example: if `current_date = 2024-12-22`, the validation period is `2023-12-23 to 2024-12-22`. - **num_month** - Budget defined per month (relative month): Limit based on the last full month. Example: if `current_date = 2024-12-22`, the validation period is `2024-11-24 to 2024-12-22`. - **num_day** - Budget defined per day enum: - num_day - num_month - num_year example: num_month maximum_discount_transaction: type: integer description: >- Maximum amount discount limit per transaction for this campaign. The limit is specified in the company's default currency. Empty if no limit is needed example: 50 stackability_properties: type: string description: Defines how the campaign stacks with others. enum: - stackability - highest_discount example: stackability priority: type: integer description: Priority of the campaign. Relevant for stackability. minimum: 1 example: 1 partner: description: The partner related to the reward nullable: true $ref: '#/components/schemas/Partner' coupon_info: description: The coupon related to the campaign if applies nullable: true $ref: '#/components/schemas/CouponInfoCampaignResponse' product_ids_rule_conditions: type: array description: >- **ONLY when rule conditions include INTERNAL product categories** List of product IDs or codes used in rule conditions for internal product categories. This field is included for easier filtering and querying of campaigns based on product involvement. string if the company use product codes, integer if the company has numeric product IDs. items: oneOf: - type: string - type: integer product_ids_rule_application: type: array description: >- **ONLY when rule application includes INTERNAL product categories** List of product IDs or codes used in rule application for internal product categories. This field is included for easier filtering and querying of campaigns based on product involvement. string if the company use product codes, integer if the company has numeric product IDs. items: oneOf: - type: string - type: integer locations_ids: type: array description: >- **ONLY when rule conditions include INTERNAL store categories** List of location IDs used in rule conditions for internal store categories. This field is included for easier filtering and querying of campaigns based on location involvement. items: type: integer location_codes: type: array description: >- **ONLY when rule conditions include INTERNAL store categories** List of location codes used in rule conditions for internal store categories. This field is included for easier filtering and querying of campaigns based on location involvement. items: type: string GetAListOfDiscountCampaignResponse: title: GetAListOfDiscountCampaignResponse type: object properties: data: type: array items: $ref: '#/components/schemas/DiscountResponse' description: '' next_token_starts_after: type: string example: data: - id: 1001 name: 25% discount on selected category description: >- Campaign offering a 25% discount on electronics when total purchase exceeds €200. category: id: 1 name: Baseline priority: 1 active: true available_from: '2025-06-01' available_to: '2025-12-31' recurrence_type: daily recurrence_days: [] currency: EUR when: after_create_activity select_customers: loyalty customer_registration_countries: - ES - FR - IT tiers: - id: 10 name: Gold Tier threshold: 500 - id: 11 name: Platinum Tier threshold: 1000 rule_conditions: > {"conditions":{"and":[{"field":"total","operator":"gte","value":200,"key":"cart.total"},{"field":"country","operator":"in","values":["ES","FR"],"key":"cart.country"}]}} application: > {"application":{"and":[{"field":"product_categories","operator":"in","values":[101,202],"key":"cart.item.product_categories","array_field":"lines"}]}} effects: > {"key":"percentage","type":"percentage","value":25,"distribution":"individual_items"} chances_to_accrue: num_month chances_to_accrue_limit: 2 budget_value: 100000 budget_period: num_month maximum_discount_transaction: 50 stackability_properties: stackability priority: 1 partner: id: 5 name: Tech Retailers Inc. description: Partnership with electronics chain image_url: https://www.partnerimage.com/logo.png - id: 1002 name: Buy 2 Get 1 Free description: 'Special promotion: for every 2 beverages purchased, get 1 free.' category: id: 2 name: Universal priority: 2 active: true available_from: '2025-09-01' available_to: '2025-11-30' recurrence_type: weekly recurrence_days: - 5 - 6 currency: USD when: after_create_activity select_customers: all_customers customer_registration_countries: - US - MX tiers: [] rule_conditions: > {"conditions":{"and":[{"array_field":"lines","field":"product_categories","operator":"in","values":[303],"key":"cart.item.product_categories"}]}} rule_application: > {"application":{"and":[{"array_field":"lines","field":"product_id","operator":"in","values":[45,46,47],"key":"cart.item.product"}]}} rule_effects: > {"key":"percentage","type":"percentage","value":"100","rule_grouped":"true",distribution":"individual_items"} chances_to_accrue: always chances_to_accrue_limit: 0 budget_value: 50000 budget_period: num_day maximum_discount_transaction: 20 stackability_properties: highest_discount priority: 2 partner: id: 7 name: Beverage Co. description: Partnership with beverage brand image_url: https://www.partnerimage.com/beverage.png - id: 8012 name: Exclusive 15% off for you description: Targeted campaign offering 15% off for selected customers. category: id: 3 name: Targeted priority: 3 active: true available_from: '2025-10-01' available_to: '2025-10-31' recurrence_type: daily recurrence_days: [] currency: EUR coupon_required: true when: after_create_activity select_customers: targeted customer_registration_countries: - ES tiers: [] rule_conditions: > {"conditions":{"and":[{"field":"total","operator":"gte","value":50,"key":"cart.total"}]}} rule_application: | {"application":{"and":[]}} rule_effects: > {"key":"percentage","type":"percentage","value":15,"distribution":"individual_items"} chances_to_accrue: always chances_to_accrue_limit: 0 budget_value: 10000 budget_period: num_month maximum_discount_transaction: 30 stackability_properties: stackability priority: 3 partner: id: 12 name: Fashion Brand description: Apparel partner image_url: https://www.partnerimage.com/fashion.png coupon_info: coupon_id: 123 static_code: SALE15OFF coupon_name: Exclusive 15% off for you external_id: EXT-8012 key: VOUCHER8012 voucher_info: voucher_id: 789 voucher_code: SALE15OFF available_redemptions: 1 max_redemptions: 1 selected: true status: pending available_from: '2025-10-01T00:00:00Z' available_to: '2025-10-31T23:59:59Z' print_from: '2025-10-01T00:00:00Z' print_to: '2025-10-31T23:59:59Z' priority: 3 printable: true next_token_starts_after: '8012' CreateNewDiscountsCampaignRequestRuleParams: title: CreateNewDiscountsCampaignRequestRuleParams type: object required: - name - loyalty_rule_category_id - select_customers - when - currency - rule_conditions - rule_effects - rule_application - stackability_properties properties: name: type: string description: >- Name of the loyalty campaign. Can be a string or a hash for multi-language names. example: 25 % discount on selected category when: type: string description: | Trigger or event that activates the campaign. Options for discounts campaigns: - after_create_activity example: after_create_activity loyalty_rule_category_id: type: integer description: ID of the campaign category. example: 1 description: type: string description: A brief description of the campaign. example: Discount for new customers. available_from: type: string format: date-time description: >- The date from which the campaign is active (YYYY-MM-DD). If you want to include time the format is YYYY-MM-DDThh:mm:ss.sss±hh:mm The available_from date must be less than the available_to date. example: '2025-10-01T08:59:59.999+00:00' available_to: type: string format: date-time description: >- The date until which the campaign is active (YYYY-MM-DD). If you want to include time the format is YYYY-MM-DDThh:mm:ss.sss±hh:mm. The available_to date must be greater than the available_from date. example: '2025-12-31T23:59:59.999+00:00' active: type: boolean description: Indicates if the campaign is active. False by default. example: true currency: type: string description: >- The currency in which the campaign is set up. must be a valid currency-code example: EUR recurrence_type: type: string description: Type of recurrence for the campaign. By default 'daily' enum: - daily - monthly_last - weekly - monthly default: daily example: daily recurrence_days: type: array description: >- Specific days for recurrence. Required if recurrence_type is 'weekly' or 'monthly'. - For weekly: 0-6 (Sunday-Saturday) - For monthly: 1-31 - Empty for daily and monthly_last. select_customers: type: string description: >- Defines the target audience for the campaign. Options are: [all_customers, loyalty, targeted] example: loyalty coupon_required: type: boolean description: >- Indicates if a coupon is required to apply the campaign. If this value is true, the promotion provided by this campaign can only be used by presenting a coupon (or by deliberately activating it through an interface) **Must be true if the campaign is targeted** example: false partner_id: type: integer description: ID of the associated partner. example: 123 customer_registration_countries: type: array description: >- Countries where the customer must be registered for the campaign to apply. items: type: string once: type: string description: >- Defines how often the campaign can be applied by customer. By default 'always' - If coupon_required is true or campaign is targeted, the possible options are: - always: The campaign can be applied as many times as the customer has coupons. - num_total: if you want to configure a maximum quantity of redemptions for the campaign and customer. - If coupon_required is false, the possible options are: - always: The campaign can be applied as many times as the customer has coupons. - num_total: if you want to configure a maximum quantity of redemptions for the campaign and customer. - num_day: if you want to configure a maximum quantity of redemptions per day for the campaign and customer. - num_month: if you want to configure a maximum quantity of redemptions per month for the campaign and customer. - num_year: if you want to configure a maximum quantity of redemptions per year for the campaign and customer. - num_month_natural: if you want to configure a maximum quantity of redemptions per natural month for the campaign and customer. - num_year_natural: if you want to configure a maximum quantity of redemptions per natural year for the campaign and customer. enum: - num_day - num_month - num_year - num_month_natural - num_year_natural - always example: num_month once_limit: type: integer description: >- The limit for 'once' parameter. If once is 'always', this value will be ignored. Required if once is different than 'always'. example: 1 chance_to_accrue_limit: type: integer description: >- Maximum number of times a campaign can be used in total (considering all customers). By default 'always'. if chance_to_accrue_period is 'always', this value will be ignored. Required if chance_to_accrue_period is different than 'always'. example: 1000 chance_to_accrue_period: type: string description: 'Period for chance_to_accrue_limit calculation. ' enum: - num_day - num_month - num_year - num_month_natural - num_year_natural - always example: num_month budget_period: type: string description: Period for budget calculation. If null, there will be no budget. enum: - num_day - num_month - num_year example: num_month budget_value: type: integer description: Value for the budget period. Required if budget_period is not null minimum: 1 example: 100000 maximum_budget_transaction: type: integer description: Maximum value awarded per transaction (in the company's currency). example: 500000 rule_conditions: type: string description: > Advanced campaign conditions (JSON object). Its mandatory to include a country condition like the one included in the example. Options for conditions depends on what you want to validate. These victory conditions will be what defines if the campaign is eligible to be applied. **Important:** Contact us for more information about the supported fields and operators. ### Supported fields and operators - **Country** (`country`): operator `in`, values are ISO codes. - **Products** (`product_id`, `product_categories`): operator `in`, values are IDs or external IDs. - **Cart attributes** (`total`, `location`, `location categories`, `payment method`, `country`): operators like `gte`, `lte`, `eq`. - **Cart item attributes** (`custom attributes`, etc.) - **Customer attributes** - **Nested conditions**: support combining conditions with quantity or total validations inside product lines. ### Example Example of a campaign that applies a discount for a country and a product with the ID 5. The campaign will be eligible if the customer is from Spain and buys more than 2 items of the product with the ID 5. ```json { "conditions": { "and": [ { "key": "country", "field": "country", "values": [ "ES" ], "operator": "in" }, { "key": "cart_product_id", "field": "product_id", "bundle": 1, "values": [ 5 ], "grouped": true, "operator": "in", "conditions": [ { "field": "quantity", "value": 2, "operator": "gte" } ], "array_field": "lines" } ] } } ``` example: conditions: and: - key: country field: country values: - ES operator: in - key: cart_product_id field: product_id values: - 5 grouped: true operator: in conditions: - field: quantity value: 2 operator: gte array_field: lines rule_effects: type: string description: > Advanced campaign effects (JSON object). A **campaign effect** defines what a customer receives when a campaign applies. The engine supports 6 effect types. Availability depends on the event type (Cart, Trigger, Custom Event, or Challenge). ### Supported effect types - **Percentage** (`percentage`): applies a percentage-based calculation. - **Direct Value** (`direct_value`): applies a fixed monetary or point value. - **Ratio** (`ratio`): defines a ratio for earning (e.g. "every X amount, give Y points/discount"). - **Strikethrough** (`strikethrough`): replaces product final price by discounted price (unit-based). - **Combo Price** (`combo_price`): sets a final price for a group of products (e.g. 2x1, 3x2, packs). - **formula** (`formula`): applies a formula to the campaign. ### Percentage Applies a percentage discount to the qualifying items or awards a percentage of the transaction value as loyalty balance. - Value: Percentage to apply. Must be > 0. Decimals supported (e.g. `0.8` = 0.8%) - Distribution: `total`, `individual_items`, or `individual_items_pro_rata` -Bundle/group: Supported — can group products into bundle conditions. This only works if victory conditions has 1 group or less. If there are more than 1 group when creating a campaign with bundle effect true it will fail **Example use case:** 15% discount on all items in the "Footwear" category when total cart exceeds €100. ### Ratio Awards a fixed amount of loyalty balance (points or wallet) for every unit of money spent. - Unit: Monetary unit per which the value is earned (must be ≥ 1). Example: `1` means "per €1 spent" - Value: Balance awarded per unit. Integer in `points` mode; decimal in `money` mode - Distribution: `total`, `individual_items`, or `individual_items_pro_rata` **Example use case (wallet mode):** Earn €0.05 wallet balance per €1 spent. ### Direct value Awards a fixed, flat amount of balance or applies a fixed discount. - Value: Fixed amount. Integer in `points` mode; decimal in `money` mode - Distribution: `total`, `individual_items`, or `individual_items_pro_rata` - Bundle/group: Supported — can group products into bundle conditions. This only works if victory conditions has 1 group or less. If there are more than 1 group when creating a campaign with bundle effect true it will fail **Example use case:** Apply a €5 flat discount when cart total exceeds €50. ### Strikethrough Displays a promotional "crossed-out" price alongside the original price, applying a monetary discount. Used to show perceived value. - `strikethrough_data`: A map of `{ product_id: promotional_price }` — one crossed-out price per product - Distribution: Always `individual_items` **Example use case:** Show "Was €29.99, Now €19.99" on product pages, applying the discount in the transaction engine. ### Combo price Sets a specific combined price for a group of products purchased together (bundle mechanics). - Value: The total price for the bundle. Must be > 0, decimals supported - Distribution: `total` or `individual_items_pro_rata` **Example use case:** Buy any 3 items from this category for €29.99 (regardless of individual prices). ### Formula (external promotional effect) Applies a discount calculated from a line-level attribute sent by an external system. Used when a third-party engine (e.g., external pricing service) pre-calculates promotional prices and sends them as line attributes. - Formula: Fixed: `lines.total - lines.attributes.promoPrice` - Distribution: Always `individual_items` - Bundle/group: Always `false` ### Distributions (summary) - `total`: The effect is applied as a single value to the transaction total - `individual_items`: The effect is applied to each qualifying line independently - `individual_items_pro_rata`: The total effect is distributed across qualifying lines proportionally by line value **Restrictions:** - `strikethrough` → `individual_items` only - `combo_price` → `total` or `individual_items_pro_rata` only - `formula` → `individual_items` only --- ### Effect limits & bundles - **Effect limit**: Maximum times this effect can apply per transaction. If not set or set to 0, applies every time conditions are met. - **Bundle/group**: Groups conditions into a bundle mechanic (e.g., buy A + B together) This only works if victory conditions has 1 group or less. If there are more than 1 group when creating a campaign with bundle effect true it will fail Effect limits and bundles are not available for Custom Event, Trigger, or Challenge events. ### Example Example of a campaign that awards 25% of each line amount as discount. ```json { "key": "percentage", "type": "percentage", "value": 25, "distribution": "individual_items", "rule_group": false, "limits": 0 } ``` example: key: percentage type: percentage value: 25 distribution: individual_items rule_group: false limits: 0 rule_application: type: string description: > Advanced campaign application logic (JSON object). This part is used to define where the campaigns apply. **Important:** You cannot put more than 1 group in this case. ### Supported fields and operators - **Products and product categories** (`product_id`, `product_categories`): operator `in`, values are IDs or external IDs. - **Payment method** (`payment_method`): operator `in`, values are slugs of payment types (e.g., `card`, `cash`). - **Additional costs** (`additional_costs`): operator `in`, values are slugs of additional costs (e.g., `shipping`, `handling`). **Important:** Contact us for more information about the supported fields and operators. ### Example Example of a campaign that applies a discount for more than 1 product with the ID 5. ```json { "conditions": { "and": [ { "key": "cart_product_id", "field": "product_id", "values": [ 5 ], "grouped": true, "operator": "in", "conditions": [ { "field": "quantity", "value": 1, "operator": "eq" } ], "array_field": "lines" } ] } } ``` example: conditions: and: - key: cart_product_id field: product_id values: - 5 grouped: true operator: in conditions: - field: quantity value: 1 operator: eq array_field: lines stackability_properties: type: string description: Defines how the campaign stacks with others. enum: - stackability - highest_discount example: stackability priority: type: integer description: >- Priority of the campaign. Relevant for stackability. Required if stackability_properties is 'stackability' minimum: 1 example: 1 CreateNewDiscountsCampaignRequestCouponParams: title: CreateNewDiscountsCampaignRequestCouponParams type: object description: >- This object defines the parameters related to coupons for a new campaign. It includes details such as the static code, availability, printing options, and other relevant attributes that determine how the coupons will be generated, distributed, and redeemed within the campaign. These parameters are essential for configuring the behavior of coupons in targeted campaigns or loyalty club promotions. **Important:** Required for targeted campaigns, all-members campaigns and loyalty club promotions that include a coupon. properties: static_code: type: string example: '{{rand_static_code}}' description: >- Required for all-members campaigns or loyalty club promotions that include a coupon. For targeted campaigns is optional **Important:** The static code can not be used more than once across all campaigns. If you attempt to use a static code that already exists in another campaign, the system will return an error indicating that the code is not unique. This ensures that each static code is associated with only one campaign, preventing conflicts and ensuring proper tracking of promotions. key: type: string example: UNIQUEKEY123 available_days: type: integer description: >- The number of days counting from the activation date until the coupon expires. **Required if you want to set relative periods for activation/expiration dates, campaign is targeted and available_delay_days is set.** Not required if you want to use fixed activation/expiration dates (taken from rule_params-> available_from and rule_params-> available_to). example: 90 available_delay_days: type: integer description: >- The number of days counting from the sent date until the coupon activates. **Required if you want to set relative periods for activation/expiration dates, campaign is targeted and available_days is set.** Not required if you want to use fixed activation/expiration dates (taken from rule_params-> available_from and rule_params-> available_to). example: 0 print_days: type: integer description: >- The total number of days between the print date and the completion of printing. By default 0. example: 90 print_delay_days: type: integer description: >- The total number of days between the activation date and the coupon is printed. By default 0. example: 0 printable: type: boolean description: if coupon is printable or not. False by default. example: true priority: type: integer description: >- Print priority if printable is true. By default, the priority is 1 for all coupons. A lower number indicates a higher priority, meaning that coupons with a priority of 1 will be printed before those with a priority of 2, and so on.' example: 1 external_id: type: string example: POS_COUPON_XYZ auto_select: type: boolean description: >- If true, coupon autoselected or auto-redeemable, depending on the system's integration type. Consequently, the customer is not required to perform any manual action to apply the discount. By default false, which means that the customer must manually select the coupon to apply the discount. example: true active: type: boolean description: >- Field accepted but ignored. Active value is taken from the rule_params -> active. Deprecated deprecated: true name: type: string description: >- Field accepted but ignored. Name value is taken from the rule_param -> name. Deprecated deprecated: true max_redemptions: type: integer description: >- Field accepted but ignored. max_redemptions value is taken from the rule_params-> once_limit. Deprecated deprecated: true available_from: type: string description: >- Field accepted but ignored. available_from value is taken from the rule_params-> available_from. Deprecated deprecated: true available_to: type: string description: >- Field accepted but ignored. available_to value is taken from the rule_params-> available_to. Deprecated deprecated: true CreateNewDiscountsCampaignRequest: title: CreateNewDiscountsCampaignRequest type: object properties: rule_params: type: object $ref: '#/components/schemas/CreateNewDiscountsCampaignRequestRuleParams' coupon_params: type: object $ref: '#/components/schemas/CreateNewDiscountsCampaignRequestCouponParams' SuccessWithId: title: SuccessWithId type: object properties: status: type: string example: success id: type: integer example: 2223222 UpdateANewCampaignRequestRuleParams: title: UpdateANewCampaignRequestRuleParams type: object properties: name: type: string description: >- Name of the loyalty campaign. Can be a string or a hash for multi-language names. example: 25 % discount on selected category when: type: string description: | Trigger or event that activates the campaign. Options for discounts campaigns: - after_create_activity Options for points campaigns: - manual - after_create_profile - refer_a_friend - after_create_activity - after_create_custom_entity - after_winning_challeng - any other ad-hoc triggers created example: after_create_activity loyalty_rule_category_id: type: integer description: ID of the campaign category. example: 1 description: type: string description: A brief description of the campaign. example: Discount for new customers. available_from: type: string format: date description: The date from which the campaign is active (YYYY-MM-DD). example: '2025-06-01' available_to: type: string format: date description: The date until which the campaign is active (YYYY-MM-DD). example: '2025-12-31' active: type: boolean description: Indicates if the campaign is active. example: true currency: type: string description: >- The currency in which the campaign is set up. must be a valid currency-code example: EUR recurrence_type: type: string description: Type of recurrence for the campaign. enum: - daily - monthly_last - weekly - monthly default: daily example: daily recurrence_days: type: array description: >- Specific days for recurrence. For weekly: 0-6 (Sunday-Saturday). For monthly: 1-31. Empty for daily and monthly_last. example: false activation_period_type: type: string description: >- Type of activation period. 'relative' if dynamic dates or 'fixed' for fixed dates. Required if rule_type is 'points' enum: - relative - fixed example: relative activation_fixed_option_selected: type: string description: >- Required if activation_period_type is 'fixed' and rule_type is 'points'. Defines fixed activation options. Options: - at_the_end_of_the_calendar_year. At the end of the current year - at_the_end_of_the_calendar_month. At the end of the current month - at_the_end_of_the_calendar_quarter. At the end of the current quarter - at_the_end_of_the_calendar_semester. At the end of the current semester - at_the_beginning_of_the_calendar_year. At the beginning of the next year - at_the_beginning_of_the_calendar_month. At the beginning of the next month - at_the_beginning_of_the_calendar_quarter. At the beginning of the next quarter - at_the_beginning_of_the_calendar_semester. At the beginning of the next semester - fixed_date. On a specific fixed date example: at_the_end_of_the_calendar_month activation_date: type: string description: >- Required if activation_period_type is 'fixed' and activation_fixed_option_selected is 'fixed_date'. The specific date when the points activates (YYYY-MM-DD). example: '2024-08-15' activation_delay: type: integer description: >- If activation_period_type is 'relative'. Delay before the campaign becomes active (in units specified by activation_delay_unit). example: 0 activation_delay_unit: type: string description: >- Unit for activation_delay. Required if rule_type is 'points' and If activation_period_type is 'relative'. enum: - days - months example: days expiration_period_type: type: string description: >- Type of expiration period. 'relative' if dynamic dates or 'fixed' for fixed dates. . Required if rule_type is 'points' enum: - fixed - relative example: relative fixed_option_selected: type: string description: >- Required if expiration_period_type is 'fixed' and rule_type is 'points'. . Defines fixed activation options. Options: - at_the_end_of_the_calendar_year. At the end of the current year - at_the_end_of_the_calendar_month. At the end of the current month - at_the_end_of_the_calendar_quarter. At the end of the current quarter - at_the_end_of_the_calendar_semester. At the end of the current semester - at_the_beginning_of_the_calendar_year. At the beginning of the next year - at_the_beginning_of_the_calendar_month. At the beginning of the next month - at_the_beginning_of_the_calendar_quarter. At the beginning of the next quarter - at_the_beginning_of_the_calendar_semester. At the beginning of the next semester - fixed_date. On a specific fixed date example: at_the_end_of_the_calendar_month availability_duration: type: integer description: >- The duration for which points remain active before they expire. Required when expiration_period_type is 'relative' and rule_type is 'points' minimum: 1 example: 30 availability_duration_unit: type: string description: >- Unit for availability_duration field. Options are 'months' or 'days'. Required if expiration_period_type is 'relative' and rule_type is 'points' enum: - days - months example: days availability_duration_natural: type: boolean description: >- Unit for availability_duration when unit is months. If true, counts natural months. example: false transferable: type: boolean description: Indicates if points are transferable. example: false partner_id: type: integer description: ID of the associated partner. example: 123 customer_registration_countries: type: array description: >- Countries where the customer must be registered for the campaign to apply. items: type: string once: type: string description: Defines how often the campaign can be applied by customer. enum: - num_day - num_month - num_year - num_month_natural - num_year_natural - always example: num_month once_limit: type: integer description: >- The limit for 'once' parameter. If once is 'always', this value will be ignored. example: 1 chance_to_accrue_limit: type: integer description: >- Maximum number of times a campaign can be used in total (considering all customers). if chance_to_accrue_period is 'always', this value will be ignored. example: 1000 chance_to_accrue_period: type: string description: Period for chance_to_accrue_limit calculation. enum: - num_day - num_month - num_year - num_month_natural num_year_natural - always example: num_month budget_period: type: string description: Period for budget calculation. enum: - num_day - num_month - num_year example: num_month budget_value: type: integer description: Value for the budget period. minimum: 1 example: 100000 maximum_budget_transaction: type: integer description: Maximum value awarded per transaction (in the company's currency). example: 500000 rule_conditions: type: string description: >- Advanced campaign conditions (JSON object). Its mandatory to include a country condition like the one included in the example. example: >- {"conditions": {"and": [{"key": "country", "field": "country", "values": ["ES"], "operator": "in"}, {"key": "cart_product_id", "field": "product_id", "bundle": 1, "values": [5], "grouped": true, "operator": "in", "conditions": [{"field": "quantity", "value": 2, "operator": "gte"}], "array_field": "lines"}]}} rule_effects: type: string description: Advanced campaign effects (JSON object). example: >- {"key": "percentage", "type": "percentage", "value": 25, "distribution": "individual_items" } rule_application: type: string description: Advanced campaign application logic (JSON object). example: >- {"conditions": {"and": [{"key": "cart_product_id", "field": "product_id", "bundle": 1, "values": [5], "grouped": true, "operator": "in", "conditions": [{"field": "quantity", "value": 1, "operator": "eq"}], "array_field": "lines"}]}} stackability_properties: type: string description: Defines how the campaign stacks with others. enum: - stackability - highest_discount example: stackability priority: type: integer description: >- Priority of the campaign. Relevant for stackability. Required if stackability.type is 'stackability' minimum: 1 example: 1 custom_entity_definition_id: type: integer description: Required if 'when' is 'after_create_custom_entity'. example: 100 UpdateANewCampaignRequestCouponParams: title: UpdateANewCampaignRequestCouponParams type: object properties: name: type: string example: Targeted Customer Discount Coupon active: type: boolean example: true static_code: type: string example: '{{rand_static_code}}' description: >- Required for all-members campaigns or loyalty club promotions that include a coupon. For targeted campaigns is optional print_from: type: string example: '2024-03-01' print_to: type: string example: '2024-09-30' key: type: string example: UNIQUEKEY123 priority: type: integer description: print priority if printable is true example: 1 available_days: type: integer description: >- The number of days counting from the activation date until the coupon expires example: 90 available_delay_days: type: integer description: >- The number of days counting from the sent date until the coupon activates example: 0 print_days: type: integer description: >- The total number of days between the print date and the completion of printing example: 90 print_delay_days: type: integer description: >- The total number of days between the activation date and the coupon is printed example: 0 printable: type: boolean description: if coupon is printable or not example: true external_id: type: string example: POS_COUPON_XYZ auto_select: type: boolean example: true available_from: type: string description: >- Activation date of the coupon in YYYY-MM-DD format. Mutually exclusive with available_days. MUST be the same value as rule_params -> available_from example: '2024-03-01' available_to: type: string description: >- Expiration date of the coupon in YYYY-MM-DD format. Mutually exclusive with available_delay_days. MUST be the same value as rule_params -> available_to example: '2025-19-30' UpdateADiscountCampaignRequest: title: UpdateADiscountCampaignRequest type: object properties: rule_params: type: object $ref: '#/components/schemas/UpdateANewCampaignRequestRuleParams' coupon_params: type: object $ref: '#/components/schemas/UpdateANewCampaignRequestCouponParams' RedeemADiscountRequest: title: RedeemADiscountRequest required: - voucher_code - static_code - customer_id - customer_code - cart_id - cart_code - discount type: object properties: voucher_code: type: string description: >- The voucher code to redeem. `voucher_code` OR `static_code` are **required** and mutually exclusive. example: '212128711' static_code: type: string description: >- The coupon code. Each static code is linked to a single campaign. **Important:** If a static code is linked to multiple vouchers, the one with the earliest expiration date will be redeemed. example: AAHY79212 customer_id: type: integer description: >- ID of the customer, is mutually exclusive to `cart_id`, `cart_code` and `customer_code`. example: 8223 customer_code: type: string description: >- Code of the customer, is mutually exclusive to `cart_id`, `cart_code` and `customer_id`. example: 8223a cart_id: type: integer description: >- ID of the cart, is mutually exclusive to `cart_code`, `customer_id` and `customer_code`. If a cart id or code is provided, the system will link the used voucher/coupon to the ticket and calculate the applied discount. example: 8223 cart_code: type: string description: >- Code of the cart, is mutually exclusive to `cart_id`, `customer_id` and `customer_code`. If a cart id or code is provided, the system will link the used voucher/coupon to the ticket and calculate the applied discount. example: 8223asf44fffdd discount: type: integer description: >- the discount applied in the voucher/coupon (in cents). This allows adjusting the campaign’s budget accordingly. example: 1500 RedeemADiscountResponse: title: RedeemADiscountResponse type: object properties: rule_id: type: integer format: int64 description: ID of the discount rule example: 555253114 campaign_history_id: type: integer format: int64 description: ID of the campaign history example: 7206 rule_name: type: string description: Name of the discount rule example: Rule name type: type: string description: Type of the rule example: discount effect_type: type: string description: Type of effect example: external_redeem distribution_type: type: string description: Distribution type of the discount example: total value: type: integer format: int64 description: Discount value example: 1500 value_as_money: type: integer format: int64 description: Discount value as money (in cents) example: 1500 select_customers: type: string description: Customer selection criteria example: targeted coupon_info: type: object description: Information about the coupon/voucher redeemed properties: voucher_id: type: integer format: int64 description: ID of the voucher example: 31176968 voucher_code: type: string description: Code of the voucher example: '212128711' coupon_id: type: integer format: int64 description: ID of the coupon example: 100004180 coupon_name: type: string description: Name of the coupon example: Coupon name static_code: type: string description: Static code of the coupon example: AAHY79212 example: rule_id: 555253114 campaign_history_id: 7206 rule_name: Rule name type: discount effect_type: external_redeem distribution_type: total value: 1500 value_as_money: 1500 select_customers: targeted coupon_info: voucher_id: 31176968 voucher_code: '212128711' coupon_id: 100004180 coupon_name: Coupon name static_code: AAHY79212 CouponInfo: title: CouponInfo nullable: true type: object properties: coupon_id: description: The ID of the coupon. type: integer format: int64 static_code: description: The static code of the coupon. type: string coupon_name: type: string example: Discount meat 50% description: Name of the coupon voucher_id: description: The ID of the voucher associated with this coupon. type: integer format: int64 voucher_code: description: The static code of the voucher associated with this coupon. type: string example: coupon_id: 123 static_code: SALE50OFF coupon_name: ' Discount meat 50%' voucher_id: 456 voucher_code: VOUCHER123 GetListDiscountsTransactionsResponse: title: GetListDiscountsTransactionsResponse type: object properties: id: description: Id of the transaction type: integer format: int64 customer_id: type: integer description: Id of the customer related with the discount customer_code: description: Code of the customer related with the discount (if present). type: string amount: type: number description: Discount amount involved in the event (currency of the cart). activity_id: type: integer description: Id of the cart purchase created_at: type: string description: 2025-12-12 23:45:00' (string) - date time of the discount origin_type: type: string description: >- Type of the origin of the discount. Possible values: "activity" when the discount was applied in a cart, "external_redemption" when the discount was applied using trigger/discount coupon_info: type: array description: Coupon information when the discount was applied using a coupon. items: $ref: '#/components/schemas/CouponInfo' next_token_starts_after: description: >- Use this token to get the next page of results using the parameter starting_after type: string DiscountTriggerRequestCustomerIDCouponID: title: Discount trigger request with customer_id and coupon_id required: - customer_id - coupon_id type: object properties: customer_id: type: number description: ID of the customer. Mutually exclusive with `customer_code`. example: 10 coupon_id: type: number description: ID of the coupon. Mutually exclusive with `loyalty_rule_id`. example: 12 external_voucher_code: type: string description: >- Optional. Code that will be used to create the Voucher. **Important:** This parameter has no validation - any value provided will be used as-is for voucher code generation. example: EXT123 priority_allocation: type: boolean description: >- Optional. When `priority_allocation` is `true`, the voucher will be generated and assigned with maximum priority. example: false DiscountTriggerRequestCustomerCodeCouponID: title: Discount trigger request with customer_code and coupon_id required: - customer_code - coupon_id type: object properties: customer_code: type: string description: Code of the customer. Mutually exclusive with `customer_id`. example: 12345a coupon_id: type: number description: ID of the coupon. Mutually exclusive with `loyalty_rule_id`. example: 12 external_voucher_code: type: string description: >- Optional. Code that will be used to create the Voucher. **Important:** This parameter has no validation - any value provided will be used as-is for voucher code generation. example: EXT123 priority_allocation: type: boolean description: >- Optional. When `priority_allocation` is `true`, the voucher will be generated and assigned with maximum priority. example: false DiscountTriggerRequestCustomerIDLoyaltyRuleID: title: Discount trigger request with customer_id and loyalty_rule_id required: - customer_id - loyalty_rule_id type: object properties: customer_id: type: number description: ID of the customer. Mutually exclusive with `customer_code`. example: 10 loyalty_rule_id: type: number description: >- ID of the loyalty rule. Mutually exclusive with `coupon_id`. Only works for **targeted** campaigns. example: 5 external_voucher_code: type: string description: >- Optional. Code that will be used to create the Voucher. **Important:** This parameter has no validation - any value provided will be used as-is for voucher code generation. example: EXT123 priority_allocation: type: boolean description: >- Optional. When `priority_allocation` is `true`, the voucher will be generated and assigned with maximum priority. example: false DiscountTriggerRequestCustomerCodeLoyaltyRuleID: title: Discount trigger request with customer_code and loyalty_rule_id required: - customer_code - loyalty_rule_id type: object properties: customer_code: type: string description: Code of the customer. Mutually exclusive with `customer_id`. example: 12345a loyalty_rule_id: type: number description: >- ID of the loyalty rule. Mutually exclusive with `coupon_id`. Only works for **targeted** campaigns. example: 5 external_voucher_code: type: string description: >- Optional. Code that will be used to create the Voucher. **Important:** This parameter has no validation - any value provided will be used as-is for voucher code generation. example: EXT123 priority_allocation: type: boolean description: >- Optional. When `priority_allocation` is `true`, the voucher will be generated and assigned with maximum priority. example: false LoyaltyRuleCategory: title: LoyaltyRuleCategory type: object nullable: true properties: id: type: integer format: int64 description: Category ID name: type: string nullable: true description: Category name priority: type: integer format: int64 nullable: true category_type: type: string nullable: true GamePrize: title: GamePrize type: object description: Prize definition within a game campaign. properties: id: type: integer format: int64 description: Prize ID game_id: type: integer format: int64 description: ID of the game this prize belongs to name: type: string description: Prize name outcome: type: string description: Outcome identifier or type display_options: type: string description: JSON or configuration for how the prize is displayed weight: type: number format: double description: Weight used for prize selection (e.g. probability) stock: type: integer description: Available stock for this prize stock_management_strategy: type: string description: Strategy for managing prize stock Game: title: Game type: object description: Game configuration attached to a game campaign (loyalty rule). properties: id: type: integer format: int64 description: Game ID loyalty_rule_id: type: integer format: int64 description: ID of the parent loyalty rule (campaign) type: type: string description: Game type identifier config: type: string description: Game configuration (e.g. JSON) template: type: string description: Template identifier or configuration game_prizes: type: array description: Prizes available in this game items: $ref: '#/components/schemas/GamePrize' GameCampaignResponse: title: GameCampaignResponse type: object description: >- Game campaign (loyalty rule of type gaming) as returned by the API. Supports multi-language via Accept-Language header. properties: id: type: integer format: int64 description: Campaign ID example: 3001 name: type: string description: >- Campaign name. If multilanguage is enabled, language of the Accept-Language header is returned. description: type: string description: >- Campaign description. If multilanguage is enabled, language of the Accept-Language header is returned. active: type: boolean description: Whether the campaign is active available_from: type: string format: date nullable: true description: Start date (YYYY-MM-DD) available_to: type: string format: date nullable: true description: End date (YYYY-MM-DD) recurrence_type: type: string description: Recurrence type (e.g. daily, weekly, monthly) recurrence_days: type: array items: type: integer format: int64 description: Days for recurrence (weekly 0-6, monthly 1-31) select_customers: type: string description: 'Audience: `loyalty` or `targeted`' customer_registration_countries: type: array items: type: string description: Countries in which the customer must be registered loyalty_rule_category: nullable: true $ref: '#/components/schemas/LoyaltyRuleCategory' rule_conditions: type: string description: JSON object with eligibility conditions rule_application: type: string description: JSON object with application logic rule_effects: type: string description: JSON object with effects configuration rule_type: type: string description: Type of loyalty rule; for games this is the gaming type example: gaming loyalty_rule_history_id: type: integer format: int64 nullable: true description: >- Loyalty rule history identifier for targeted game snapshots. Returned when the game detail is resolved from history context (for example `search_by=loyalty_rule_history_id`). example: 900004 game: nullable: true $ref: '#/components/schemas/Game' priority: type: integer format: int64 nullable: true stackability_properties: type: string nullable: true when: type: string once: type: string once_limit: type: integer format: int64 nullable: true GameCampaignAvailableResponse: title: GameCampaignAvailableResponse allOf: - $ref: '#/components/schemas/GameCampaignResponse' - type: object properties: loyalty_rule_history_id: type: integer format: int64 nullable: true description: >- Loyalty rule history identifier assigned to the customer for targeted game campaigns. This field is returned only when the game campaign audience is `targeted`. example: 900004 GetAListOfGameCampaignResponse: title: GetAListOfGameCampaignResponse type: object properties: data: type: array items: $ref: '#/components/schemas/GameCampaignAvailableResponse' description: List of game campaigns next_token_starts_after: type: string description: >- Cursor for the next page; use as `starting_after` in the next request example: data: - id: 3001 name: Spin the Wheel description: Spin to win a prize on your next visit. active: true available_from: '2025-01-01' available_to: '2025-12-31' recurrence_type: daily recurrence_days: [] select_customers: loyalty customer_registration_countries: - ES - FR rule_type: gaming game: id: 1 loyalty_rule_id: 3001 type: wheel config: '{}' template: default game_prizes: - id: 1 game_id: 1 name: 10% discount outcome: discount display_options: '{}' weight: 0.5 stock: 100 stock_management_strategy: decrement - id: 3002 name: Targeted Lucky Wheel description: Special game campaign for selected customers. active: true available_from: '2025-01-01' available_to: '2025-12-31' recurrence_type: daily recurrence_days: [] select_customers: targeted loyalty_rule_history_id: 900004 customer_registration_countries: - ES rule_type: gaming game: id: 2 loyalty_rule_id: 3002 type: wheel config: '{}' template: default game_prizes: - id: 2 game_id: 2 name: 50 points outcome: points display_options: '{}' weight: 0.4 stock: 500 stock_management_strategy: decrement next_token_starts_after: '3001' GamePlayRequest: title: GamePlayRequest type: object description: >- Request body to play a game. Exactly one of `customer_id` or `customer_code` must be provided to identify the customer. additionalProperties: false properties: customer_id: type: integer format: int64 description: ID of the customer. Mutually exclusive with `customer_code`. minimum: 1 maximum: 9223372036854776000 example: 8223342 customer_code: type: string maxLength: 255 description: Code of the customer. Mutually exclusive with `customer_id`. example: 8223a loyalty_rule_history_id: type: integer format: int64 minimum: 1 maximum: 9223372036854776000 description: >- Optional loyalty rule history identifier. For targeted audience game campaigns, send the history ID assigned to the customer. If it is missing or does not match, the play returns `200` with an empty `effects` array. example: 900004 anyOf: - required: - customer_id - required: - customer_code GamePlayEffect: title: GamePlayEffect type: object description: Single effect returned for a game play (one prize outcome applied). properties: game_info: type: object description: Game and prize outcome details. properties: config: type: string description: >- Game configuration (e.g. JSON with defeat_message, victory_message). game_id: type: integer format: int64 description: ID of the game. game_type: type: string description: Type of game (e.g. wheel). outcome: type: string description: >- Outcome payload as JSON text. Contains promotion data for won prizes, or `{}` when no prize was won. prize_id: type: integer format: int64 description: ID of the prize that was selected. status: type: string description: Result of the play. enum: - won - no_prize - stock_exhausted status_message: type: string description: >- Human-readable status (e.g. "Prize won and applied successfully" or "No prize won (outcome empty)"). template: type: object nullable: true description: Nullable template value returned by the game service. properties: String: type: string description: Template value. Valid: type: boolean description: Whether the template value is present. won_prize: type: object description: >- Prize details returned when `status` is `won`. Omitted when no prize was won. properties: points: type: integer description: Points awarded when the prize type is `points`. available_from: type: string format: date description: Start date for a discount prize. available_to: type: string format: date description: End date for a discount prize. image_url: type: string description: Image URL for a discount prize. name: type: string description: Name of the won prize (points, discount or coupon). description: type: string description: Description of a coupon prize. type: type: string description: Type of prize won. enum: - points - discount - coupon line: type: integer description: Line index (e.g. 0 for games without cart lines). order_apply: type: integer description: Order of application. rule_id: type: integer format: int64 description: ID of the loyalty rule (game campaign). rule_name: type: string description: Name of the game campaign. rule_unique_id: type: string description: Unique identifier of the rule. select_customers: type: string description: Customer audience configured for the game campaign. enum: - all_customers - loyalty - targeted example: loyalty type: type: string description: Effect type; for game plays this is "gaming". example: gaming GamePlayResponse: title: GamePlayResponse type: object description: >- Response after a game play. Effects contain the selected game outcome (e.g. discount prize, points prize, no prize, or stock exhausted) when the customer can play the game. If the customer and game do not match, `effects` is empty. properties: code: type: string description: Result code example: success effects: type: array description: >- List of effects applied for this play. Each item describes the selected prize, game info, and the rule that applied. Empty when the customer cannot play this game because eligibility or targeting conditions do not match. When no prize is selected, the item is returned with `game_info.status` set to `no_prize`. When a prize is selected but stock is exhausted, the item is returned with `game_info.status` set to `stock_exhausted`. items: $ref: '#/components/schemas/GamePlayEffect' example: code: success effects: - game_info: config: '{"defeat_message": "lose", "victory_message": "win"}' game_id: 101 game_type: scratch outcome: '{"promotion_id": 1234568150, "promotion_type": "points"}' prize_id: 125 status: won status_message: Prize won and applied successfully template: String: '' Valid: false won_prize: points: 100 type: points line: 0 order_apply: 0 rule_id: 1234568641 rule_name: test play rule_unique_id: '1234568641' select_customers: loyalty type: gaming ScoresResponse: title: ScoresResponse type: object properties: id: description: >- The ID of the campaign for loyalty or all_members campaigns. For targeted campaigns it returns the id of the loyalty rule history. type: integer example: 1001 name: description: >- Name of the loyalty campaign. Can be a string or a hash for multi-language names. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. type: string example: 10 extra points on selected category description: description: >- The description of the loyalty campaign. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. type: string category: description: Category of the points campaign nullable: true $ref: '#/components/schemas/CategoryCampaign' active: type: boolean description: Indicates if the campaign is active. example: true available_from: type: string format: date description: The date from which the campaign is active (YYYY-MM-DD). example: '2025-06-01' available_to: type: string format: date description: The date until which the campaign is active (YYYY-MM-DD). example: '2025-12-31' recurrence_type: type: string description: Type of recurrence for the campaign. enum: - daily - monthly_last - weekly - monthly default: daily example: daily recurrence_days: type: array description: >- Specific days for recurrence. For weekly: 0-6 (Sunday-Saturday). For monthly: 1-31. Empty for daily and monthly_last. currency: type: string description: Campaign Currency. Currency in which this campaign runs (iso-code) example: EUR coupon_required: type: boolean description: >- Indicates if a coupon is required to apply the campaign. If this value is true, the promotion provided by this campaign can only be used by presenting a coupon (or by deliberately activating it through an interface) **Must be true if the campaign is targeted** example: false when: type: string description: > Trigger or event that activates the campaign. Options: - `after_create_activity`: This is a general event triggered after a purchase is done. The loyalty campaign tied to this event would typically reward points or benefits based on the activity completed. Examples include: - Awarding points for every euro spent. - Offering bonus points for purchasing specific products or categories. - `manual`: This refers to a loyalty campaign that is triggered manually by an administrator or a system user. It's not automated and requires a specific action to be initiated. This could be used for a one-off reward, a special bonus, or to rectify a customer's account. - `after_create_profile`: This event is automatically triggered when a new customer profile is successfully created in the system. A loyalty campaign tied to this event would typically reward a new user for signing up. Examples include: - Giving a welcome bonus of 50 points. - Assigning the user to a specific loyalty tier. - `refer_a_friend`: This event is triggered when a customer successfully refers a new user who then signs up or makes a purchase. The campaigns's trigger would likely be tied to the new user's action, rewarding both the referrer and the new user. Examples include: - Rewarding the referrer and referral with 100 points for each successful referral. - `after_create_custom_entity`: This event is triggered after a new instance of a "custom entity" is created. A custom entity is a non-standard data object that is specific to your business needs and not part of the core system architecture. Examples could include: - After a customer creates a wishlist, they receive 20 points. - When a user submits a product review, they earn 10 points. - `after_winning_challenge`: This event is triggered when a customer successfully completes and wins a challenge. Challenges are often a gamified element of a loyalty program, where customers are encouraged to perform a series of actions to achieve a goal. Examples include: - Challenge: "Spend $200 in a month": The event is triggered when the user reaches the $200 spending threshold. - Challenge: "Purchase from 3 different categories": The event is triggered when the user has bought items from the third category. - `any other ad-hoc triggers created`: This is a catch-all category for any other custom-defined events. These are triggers that are not part of the standard set of events and are created for specific, non-recurring, or unique business needs. These could be: - `after_update_profile`: Triggered when a user updates their personal information. - `after_participate_in_event`: Triggered when a user RSVPs or attends a special event. - `after_complete_tutorial`: Triggered when a new user finishes a product or site tutorial. example: after_create_activity select_customers: type: string description: |- 'Defines the target audience for the campaign. Options are: - `loyalty` for loyalty members campaigns - `targeted` for specific customers or segments example: loyalty customer_registration_countries: type: array description: >- Countries in which the customer must be registered for campaign eligibility items: type: string achievement_definitions: description: Tiers customers need to reach to qualify for the campaign type: array items: $ref: '#/components/schemas/AchievementDefinitionResponse' rule_conditions: description: > Advanced campaign conditions, represented as a JSON object. These conditions defines complex eligibility conditions for campaigns, combining logical operators (`and`, `or`) with different fields such as cart totals, country, payment methods, store locations, product IDs, product categories, and custom attributes. ### Supported fields and operators - **Numbers** (`total`, `quantity`, `total_net`): operators include `gte`, `lte`, `eq`, etc. - **Country** (`country`): operator `in`, values are ISO codes. - **Payment methods** (`payment_method`): operator `in`, values are slugs of payment types (e.g., `card`, `cash`). - **Stores** (`location_id`): operator `in`, values are store IDs. - **Store categories** (`location_categories`): operator `in`, values are category IDs. - **Products** (`product_id`, `product_categories`): operator `in`, values are IDs or external IDs. - **Cart item attributes** (`custom1`, `custom5`, etc.): operators like `eq`. - **Nested conditions**: support combining conditions with quantity or total validations inside product lines. - **Custom entities attributes values** (`custom_entity_{id}`): operators like `eq`, `in`, etc. - **Challenges** (`challenge_{id}`): operators like `eq`, `in`, etc. ### Example ```json { "conditions": { "and": [ { "field": "total", "operator": "gte", "value": 100, "key": "cart.total" }, { "field": "country", "operator": "in", "values": ["ES","UY","AR"], "key": "cart.country" }, { "array_field": "payments", "field": "type", "operator": "in", "values": ["card","cash","U","V","debit_card"], "key": "cart.payment_method" }, { "field": "location_id", "operator": "in", "values": [1,2,3,4], "key": "cart.location_id" }, { "field": "location_categories", "operator": "in", "values": [3,4,2,1], "key": "cart.location_feature" }, { "array_field": "lines", "field": "product_id", "key": "cart.item.product", "bundle": "2", "operator": "in", "values": [1], "grouped": true, "conditions": [ { "field": "quantity", "operator": "gte", "value": 2 }, { "field": "total", "operator": "gte", "value": 200 } ] }, { "array_field": "lines", "field": "product_categories", "key": "cart.item.product_categories", "bundle": "2", "operator": "in", "values": [45454] }, { "array_field": "lines", "field": "product_categories", "key": "cart.item.product_category", "operator": "in", "values": [2, 43, 232], "grouped": true, "conditions": [ { "field": "total_net", "operator": "gte", "value": 150 } ] } ] } } ``` example: >- {"conditions": {"and": [{"key": "cart_product_id", "field": "product_id", "bundle": 1, "values": [5], "grouped": true, "operator": "in", "conditions": [{"field": "quantity", "value": 1, "operator": "eq"}], "array_field": "lines"}]}} rule_application: type: string description: > Advanced campaign application logic (JSON object). This field defines how the campaign is applied to the cart, specifying which items or conditions must be met for the promotion to take effect. It uses a similar structure to `rule_conditions`, allowing for complex conditions based on product IDs, categories, quantities, and other attributes. ### Example ```json { "application": { "and": [ { "array_field": "lines", "field": "product_id", "key": "cart.item.product", "bundle": "1", "operator": "in", "values": [5], "grouped": true, "conditions": [ { "field": "quantity", "operator": "eq", "value": 1 } ] } ] } } ``` example: >- {"application": {"and": [{"key": "cart_product_id", "field": "product_id", "bundle": 1, "values": [5], "grouped": true, "operator": "in", "conditions": [{"field": "quantity", "value": 1, "operator": "eq"}], "array_field": "lines"}]}} rule_effects: type: string description: | Advanced campaign effects (JSON object). Supported effect types include: - **percentage** → applies a promotion percentage on ticket/cart lines. - **direct_value** → fixed amount of points applied. - **ratio** → Every x monetary unit you get a x amount of points/wallet (e.g. for every 20 euros spent in Beverage you get 10 points). - **strikethrough** → replaces product final price by discounted price (unit-based) and grants you the difference equivalent in points. - **combo_price** → sets a final price for a group of products (e.g. 2x1, 3x2, packs) and grants you the difference equivalent in points. - **informative** → no monetary effect; displays an informational message. Distribution modes supported: - `total` → applies to total ticket. - `individual_items` → applies to each impacted line individually. - `individual_items_pro_rata` → prorates total effect across impacted lines. ### Example ```json { "key": "percentage", "type": "percentage", "value": 25, "distribution": "individual_items" } ``` example: >- {"key": "percentage", "type": "percentage", "value": 25, "distribution": "individual_items" } once: type: string description: >- Defines how many times a customer can win the specified campaign. Possible values are: - **always** : No limit on the number of times a customer can win. - **num_year** - Number of times per year (relative year): Limit based on the last 12 months. Example: if `current_date = 2024-12-22`, the validation period is `2023-12-23 to 2024-12-22`. - **num_month** - Number of times per month (relative month): Limit based on the last full month. Example: if `current_date = 2024-12-22`, the validation period is `2024-11-24 to 2024-12-22`. - **num_year_natural** - Number of times per year (natural year): Limit within the current calendar year. Example: if `current_date = 2024-12-22`, the validation period is `2024-01-01 to 2024-12-31`. - **num_month_natural** - Number of times per month (natural month): Limit within the current calendar month. Example: if `current_date = 2024-12-22`, the validation period is `2024-12-01 to 2024-12-31`. - **num_day** - Number of times per natural day: Limit within a natural day (from 00:00 to 23:59). - **num_total** - Total number of times: Limit across all history, without date restriction. enum: - num_day - num_month - num_year - always - num_total example: num_month once_limit: type: integer description: >- The limit for once parameter. If once is 'always', this value will be ignored. example: 1 chances_to_accrue_period: type: string description: >- Defines how many times in total (considering all customers) the specified discount campaign may apply. Possible values are: - **always** : No limit on the number of times a customer can win. - **num_year** - Number of times per year (relative year): Limit based on the last 12 months. Example: if `current_date = 2024-12-22`, the validation period is `2023-12-23 to 2024-12-22`. - **num_month** - Number of times per month (relative month): Limit based on the last full month. Example: if `current_date = 2024-12-22`, the validation period is `2024-11-24 to 2024-12-22`. - **num_year_natural** - Number of times per year (natural year): Limit within the current calendar year. Example: if `current_date = 2024-12-22`, the validation period is `2024-01-01 to 2024-12-31`. - **num_month_natural** - Number of times per month (natural month): Limit within the current calendar month. Example: if `current_date = 2024-12-22`, the validation period is `2024-12-01 to 2024-12-31`. - **num_day** - Number of times per natural day: Limit within a natural day (from 00:00 to 23:59). - **num_total** - Total number of times: Limit across all history, without date restriction. enum: - num_day - num_month - num_year - always - num_total example: num_month chances_to_accrue_limit: type: integer description: >- The limit for chances_to_accrue_period parameter. If once is 'always', this value will be ignored. example: 1 budget_value: type: integer description: >- Maximum budget limit for this campaign. The limit is specified in the company's default currency. if budget_period is "Unlimited", this value will be ignored. We always use the monetary equivalent of points to check this limit. minimum: 1 example: 100000 budget_period: type: string description: >- Period for budget calculation. Empty if unlimited. - **unlimited or empty** : No limit on the budget. - **num_year** - Budget defined per year (relative year): Limit based on the last 12 months. Example: if `current_date = 2024-12-22`, the validation period is `2023-12-23 to 2024-12-22`. - **num_month** - Budget defined per month (relative month): Limit based on the last full month. Example: if `current_date = 2024-12-22`, the validation period is `2024-11-24 to 2024-12-22`. - **num_day** - Budget defined per day enum: - num_day - num_month - num_year example: num_month maximum_discount_transaction: type: integer description: >- Maximum amount limit per transaction for this campaign. The limit is specified in the company's default currency. Empty if no limit is needed. We always use the monetary equivalent of points to check this limit. example: 50 activation_period_type: type: string description: Type of activation period. enum: - fixed - relative example: relative activation_delay: type: integer description: >- if activation_period_type is 'relative', Delay before the points given by the campaign becomes active (in units specified by activation_delay_unit). example: 0 activation_delay_unit: type: string description: >- if activation_period_type is 'relative', Unit for activation_delay (the delay before the points given by the campaign becomes active). enum: - days - months example: days activation_fixed_option_selected: type: string description: |- Required if activation_period_type is 'fixed'. Options: - `at_the_end_of_the_calendar_year` - at the end of the year - `at_the_end_of_the_calendar_month` - at the end of the month - `at_the_end_of_the_calendar_quarter` - at the end of the quarter - `at_the_end_of_the_calendar_semester` - at the end of the semester - `at_the_beginning_of_the_calendar_year` - At the beginning of the next year - `at_the_beginning_of_the_calendar_month` - At the beginning of the next month - `at_the_beginning_of_the_calendar_quarter` - At the beginning of the next quarter - `at_the_beginning_of_the_calendar_semester` - At the beginning of the next semester - fixed_date` example: at_the_beginning_of_the_calendar_month activation_date: type: string format: date description: >- Required if activation_period_type is 'fixed' and activation_fixed_option_selected is 'fixed_date'. Date when the points given by the campaign become active (YYYY-MM-DD). example: '2025-12-31' expiration_period_type: type: string description: Type of expiration period. enum: - fixed - relative example: relative availability_duration: type: integer description: >- if expiration_period_type is 'relative', Delay before the points given by the campaign becomes active (in units specified by activation_delay_unit). minimum: 1 example: 12 availability_duration_unit: type: string description: >- if expiration_period_type is 'relative', Unit for availability_duration (the delay before the points given by the campaign expire). enum: - days - months example: days fixed_option_selected: type: string description: |- Required if expiration_period_type is 'fixed'. Options: - `at_the_end_of_the_calendar_year` - at the end of the year - `at_the_end_of_the_calendar_month` - at the end of the month - `at_the_end_of_the_calendar_quarter` - at the end of the quarter - `at_the_end_of_the_calendar_semester` - at the end of the semester - `at_the_beginning_of_the_calendar_year` - At the beginning of the next year - `at_the_beginning_of_the_calendar_month` - At the beginning of the next month - `at_the_beginning_of_the_calendar_quarter` - At the beginning of the next quarter - `at_the_beginning_of_the_calendar_semester` - At the beginning of the next semester - fixed_date` example: at_the_end_of_the_calendar_year expiration_date: type: string format: date description: >- Required if expiration_period_type is 'fixed' and fixed_option_selected is 'fixed_date'. Date when the points given by the campaign expire (YYYY-MM-DD). example: '2025-12-31' stackability_properties: type: string description: Defines how the campaign stacks with others. enum: - stackability - highest_discount example: stackability priority: type: integer description: Priority of the campaign. Relevant for stackability. minimum: 1 example: 1 custom_entity_definition_id: type: integer description: Required if 'when' is 'after_create_custom_entity'. example: 100 transferable: type: boolean description: Indicates if points are transferable. example: false partner_id: type: integer description: ID of the associated partner. example: 123 coupon_info: description: The coupon related to the campaign if applies nullable: true $ref: '#/components/schemas/CouponInfoCampaignResponse' GetAListOfScoreCampaignResponse: title: GetAListOfScoreCampaignResponse type: object properties: data: type: array items: $ref: '#/components/schemas/ScoresResponse' description: '' next_token_starts_after: type: string example: data: - id: 2001 name: 10 extra points on beverages description: Earn 10 extra points when buying any beverage over $5. category: id: 1 name: Baseline priority: 1 active: true available_from: '2025-01-01' available_to: '2025-12-31' recurrence_type: daily recurrence_days: [] currency: USD when: after_create_activity select_customers: loyalty customer_registration_countries: - US - MX achievement_definitions: - id: 1 name: Bronze Tier threshold: 100 rule_conditions: > {"conditions":{"and":[{"field":"total","operator":"gte","value":5,"key":"cart.total"},{"array_field":"lines","field":"product_categories","operator":"in","values":[303],"key":"cart.item.product_categories"}]}} rule_application: > {"application":{"and":[{"array_field":"lines","field":"product_id","operator":"in","values":[45,46,47],"key":"cart.item.product"}]}} rule_effects: > {"key":"direct_value","type":"direct_value","value":10,"distribution":"individual_items"} chances_to_accrue: num_day chances_to_accrue_limit: 1 budget_value: 50000 budget_period: num_month maximum_discount_transaction: 20 activation_period_type: relative activation_delay: 0 activation_delay_unit: days expiration_period_type: relative availability_duration: 30 availability_duration_unit: days stackability_properties: stackability priority: 1 transferable: false partner_id: 101 - id: 2002 name: Back to School Promo description: 20% cashback return on all stationery during September. category: id: 2 name: Universal priority: 2 active: true available_from: '2025-09-01' available_to: '2025-09-30' recurrence_type: monthly recurrence_days: - 1 - 15 currency: EUR when: after_create_activity select_customers: loyalty customer_registration_countries: - ES - FR achievement_definitions: [] rule_conditions: > {"conditions":{"and":[{"array_field":"lines","field":"product_categories","operator":"in","values":[101,102],"key":"cart.item.product_categories"}]}} rule_application: > {"application":{"and":[{"array_field":"lines","field":"product_id","operator":"in","values":[501,502,503],"key":"cart.item.product"}]}} rule_effects: > {"key":"percentage","type":"percentage","value":20,"distribution":"individual_items"} chances_to_accrue: always chances_to_accrue_limit: 0 budget_value: 100000 budget_period: num_year maximum_discount_transaction: 100 activation_period_type: fixed activation_fixed_option_selected: at_the_beginning_of_the_calendar_month activation_date: '2025-09-01' expiration_period_type: fixed fixed_option_selected: at_the_end_of_the_calendar_month expiration_date: '2025-09-30' stackability_properties: highest_discount priority: 2 transferable: true partner_id: 202 - id: 8013 name: Special targeted bonus description: Targeted campaign offering 50 extra points. category: id: 3 name: Targeted priority: 3 active: true available_from: '2025-10-01' available_to: '2025-10-31' recurrence_type: daily recurrence_days: [] currency: EUR when: after_create_activity select_customers: targeted customer_registration_countries: - ES achievement_definitions: [] rule_conditions: > {"conditions":{"and":[{"field":"total","operator":"gte","value":100,"key":"cart.total"}]}} rule_application: | {"application":{"and":[]}} rule_effects: > {"key":"direct_value","type":"direct_value","value":50,"distribution":"individual_items"} chances_to_accrue: always chances_to_accrue_limit: 0 budget_value: 20000 budget_period: num_month maximum_discount_transaction: 0 activation_period_type: relative activation_delay: 0 activation_delay_unit: days expiration_period_type: relative availability_duration: 30 availability_duration_unit: days stackability_properties: stackability priority: 3 transferable: false partner_id: 303 coupon_required: true coupon_info: coupon_id: 456 static_code: POINTS50 coupon_name: Special targeted bonus external_id: EXT-8013 key: VOUCHER8013 voucher_info: voucher_id: 987 voucher_code: POINTS50 available_redemptions: 1 max_redemptions: 1 selected: true status: pending available_from: '2025-10-01T00:00:00Z' available_to: '2025-10-31T23:59:59Z' print_from: '2025-10-01T00:00:00Z' print_to: '2025-10-31T23:59:59Z' priority: 3 printable: true next_token_starts_after: '8013' CreateNewPointsCampaignRequestRuleParams: title: CreateNewPointsCampaignRequestRuleParams type: object required: - name - loyalty_rule_category_id - select_customers - when - currency - rule_conditions - rule_effects - rule_application - stackability_properties properties: name: type: string description: >- Name of the loyalty campaign. Can be a string or a hash for multi-language names. example: 25 % discount on selected category when: type: string description: | Trigger or event that activates the campaign. Options for points campaigns: - manual - after_create_profile - refer_a_friend - after_create_activity - after_create_custom_entity - after_winning_challenge - any other ad-hoc triggers created example: after_create_activity loyalty_rule_category_id: type: integer description: ID of the campaign category. example: 1 description: type: string description: A brief description of the campaign. example: Discount for new customers. available_from: type: string format: date-time description: >- The date from which the campaign is active (YYYY-MM-DD). If you want to include time the format is YYYY-MM-DDThh:mm:ss.sss±hh:mm The available_from date must be less than the available_to date. example: '2025-10-01T08:59:59.999+00:00' available_to: type: string format: date-time description: >- The date until which the campaign is active (YYYY-MM-DD). If you want to include time the format is YYYY-MM-DDThh:mm:ss.sss±hh:mm. The available_to date must be greater than the available_from date. example: '2025-12-31T23:59:59.999+00:00' active: type: boolean description: Indicates if the campaign is active. False by default. example: true currency: type: string description: >- The currency in which the campaign is set up. must be a valid currency-code example: EUR recurrence_type: type: string description: Type of recurrence for the campaign. By default 'daily' enum: - daily - monthly_last - weekly - monthly default: daily example: daily recurrence_days: type: array description: >- Specific days for recurrence. Required if recurrence_type is 'weekly' or 'monthly'. - For weekly: 0-6 (Sunday-Saturday) - For monthly: 1-31 - Empty for daily and monthly_last. select_customers: type: string description: >- Defines the target audience for the campaign. Options are: [all_customers, loyalty, targeted] example: loyalty coupon_required: type: boolean description: >- Indicates if a coupon is required to apply the campaign. If this value is true, the promotion provided by this campaign can only be used by presenting a coupon (or by deliberately activating it through an interface) **Must be true if the campaign is targeted** example: false activation_period_type: type: string description: >- Type of activation period. 'relative' if dynamic dates or 'fixed' for fixed dates. By default 'relative'. Required if rule_type is 'points' enum: - relative - fixed example: relative activation_fixed_option_selected: type: string description: >- Required if activation_period_type is 'fixed' and rule_type is 'points'. Defines fixed activation options. Options: - at_the_end_of_the_calendar_year. At the end of the current year - at_the_end_of_the_calendar_month. At the end of the current month - at_the_end_of_the_calendar_quarter. At the end of the current quarter - at_the_end_of_the_calendar_semester. At the end of the current semester - at_the_beginning_of_the_calendar_year. At the beginning of the next year - at_the_beginning_of_the_calendar_month. At the beginning of the next month - at_the_beginning_of_the_calendar_quarter. At the beginning of the next quarter - at_the_beginning_of_the_calendar_semester. At the beginning of the next semester - fixed_date. On a specific fixed date example: at_the_end_of_the_calendar_month activation_date: type: string description: >- The specific date when the points activates (YYYY-MM-DD). Required if activation_period_type is 'fixed' and activation_fixed_option_selected is 'fixed_date' and rule_type is 'points'. The activation date can not be greater than the expiration date. If you attempt to set an activation date that is after the expiration date, the system will return an error indicating that the activation date must be before the expiration date. example: '2024-08-15' expiration_date: type: string description: >- Required if expiration_period_type is 'fixed' and fixed_option_selected = 'fixed_date' and rule_type is 'points'. The specific date when the points expire (YYYY-MM-DD). The expiration date can not be less than the activation_date. example: '2024-12-31' activation_delay: type: integer description: >- Required If activation_period_type is 'relative'. Delay before the campaign becomes active (in units specified by activation_delay_unit). example: 0 activation_delay_unit: type: string description: >- Unit for activation_delay. Required if rule_type is 'points' and If activation_period_type is 'relative'. enum: - days - months example: days expiration_period_type: type: string description: >- Type of expiration period. 'relative' if dynamic dates or 'fixed' for fixed dates. By default 'relative'. Required if rule_type is 'points' enum: - fixed - relative example: relative fixed_option_selected: type: string description: >- Required if expiration_period_type is 'fixed' and rule_type is 'points'. . Defines fixed activation options. Options: - at_the_end_of_the_calendar_year. At the end of the current year - at_the_end_of_the_calendar_month. At the end of the current month - at_the_end_of_the_calendar_quarter. At the end of the current quarter - at_the_end_of_the_calendar_semester. At the end of the current semester - at_the_beginning_of_the_calendar_year. At the beginning of the next year - at_the_beginning_of_the_calendar_month. At the beginning of the next month - at_the_beginning_of_the_calendar_quarter. At the beginning of the next quarter - at_the_beginning_of_the_calendar_semester. At the beginning of the next semester - fixed_date. On a specific fixed date example: at_the_end_of_the_calendar_month availability_duration: type: integer description: >- The duration for which points remain active before they expire. Required when expiration_period_type is 'relative' and rule_type is 'points' minimum: 1 example: 30 availability_duration_unit: type: string description: >- Unit for availability_duration field. Options are 'months' or 'days'. Required if expiration_period_type is 'relative' and rule_type is 'points' enum: - days - months example: days availability_duration_natural: type: boolean description: >- Unit for availability_duration when unit is months. If true, counts natural months. example: false transferable: type: boolean description: Indicates if points are transferable. False by default. example: false partner_id: type: integer description: ID of the associated partner. example: 123 customer_registration_countries: type: array description: >- Countries where the customer must be registered for the campaign to apply. items: type: string once: type: string description: >- Defines how often the campaign can be applied by customer. By default 'always' - If coupon_required is true or campaign is targeted, the possible options are: - always: The campaign can be applied as many times as the customer has coupons. - num_total: if you want to configure a maximum quantity of redemptions for the campaign and customer. - If coupon_required is false, the possible options are: - always: The campaign can be applied as many times as the customer has coupons. - num_total: if you want to configure a maximum quantity of redemptions for the campaign and customer. - num_day: if you want to configure a maximum quantity of redemptions per day for the campaign and customer. - num_month: if you want to configure a maximum quantity of redemptions per month for the campaign and customer. - num_year: if you want to configure a maximum quantity of redemptions per year for the campaign and customer. - num_month_natural: if you want to configure a maximum quantity of redemptions per natural month for the campaign and customer. - num_year_natural: if you want to configure a maximum quantity of redemptions per natural year for the campaign and customer. enum: - num_day - num_month - num_year - num_month_natural - num_year_natural - always example: num_month once_limit: type: integer description: >- The limit for 'once' parameter. If once is 'always', this value will be ignored. Required if once is different than 'always'. example: 1 chance_to_accrue_limit: type: integer description: >- Maximum number of times a campaign can be used in total (considering all customers). By default 'always'. if chance_to_accrue_period is 'always', this value will be ignored. Required if chance_to_accrue_period is different than 'always'. example: 1000 chance_to_accrue_period: type: string description: 'Period for chance_to_accrue_limit calculation. ' enum: - num_day - num_month - num_year - num_month_natural - num_year_natural - always example: num_month budget_period: type: string description: Period for budget calculation. If null, there will be no budget. enum: - num_day - num_month - num_year example: num_month budget_value: type: integer description: Value for the budget period. Required if budget_period is not null minimum: 1 example: 100000 maximum_budget_transaction: type: integer description: Maximum value awarded per transaction (in the company's currency). example: 500000 rule_conditions: type: string description: > Advanced campaign conditions (JSON object). Its mandatory to include a country condition like the one included in the example. Options for conditions depends on what you want to validate. These victory conditions will be what defines if the campaign is eligible to be applied. **Important:** Contact us for more information about the supported fields and operators. ### Supported fields and operators - **Country** (`country`): operator `in`, values are ISO codes. - **Products** (`product_id`, `product_categories`): operator `in`, values are IDs or external IDs. - **Cart attributes** (`total`, `location`, `location categories`, `payment method`, `country`): operators like `gte`, `lte`, `eq`. - **Cart item attributes** (`custom attributes`, etc.) - **Customer attributes** - **Nested conditions**: support combining conditions with quantity or total validations inside product lines. ### Example Example of a campaign that awards points for a country and a product with the ID 5. The campaign will be eligible if the customer is from Spain and buys more than 2 items of the product with the ID 5. ```json { "conditions": { "and": [ { "key": "country", "field": "country", "values": [ "ES" ], "operator": "in" }, { "key": "cart_product_id", "field": "product_id", "bundle": 1, "values": [ 5 ], "grouped": true, "operator": "in", "conditions": [ { "field": "quantity", "value": 2, "operator": "gte" } ], "array_field": "lines" } ] } } ``` example: conditions: and: - key: country field: country values: - ES operator: in - key: cart_product_id field: product_id values: - 5 grouped: true operator: in conditions: - field: quantity value: 2 operator: gte array_field: lines rule_effects: type: string description: > Advanced campaign effects (JSON object). A **campaign effect** defines what a customer receives when a campaign applies. The engine supports 6 effect types. Availability depends on the event type (Cart, Trigger, Custom Event, or Challenge). ### Supported effect types - **Percentage** (`percentage`): applies a percentage-based calculation. - **Direct Value** (`direct_value`): applies a fixed monetary or point value. - **Ratio** (`ratio`): defines a ratio for earning (e.g. "every X amount, give Y points"). - **Strikethrough** (`strikethrough`): replaces product final price by discounted price (unit-based) and grants you the difference equivalent in points. - **Combo Price** (`combo_price`): sets a final price for a group of products (e.g. 2x1, 3x2, packs) and grants you the difference equivalent in points. ### Percentage Applies a percentage amount of points to the qualifying items or awards a percentage of the transaction value as points. - Value: Percentage to apply. Must be > 0. Decimals supported (e.g. `0.8` = 0.8%) - Distribution: `total`, `individual_items`, or `individual_items_pro_rata` - Bundle/group: Supported — can group products into bundle conditions. This only works if victory conditions has 1 group or less. If there are more than 1 group when creating a campaign with bundle effect true it will fail **Example use case:** 15% of the cart total is awarded as points. ### Ratio Awards a fixed amount of loyalty balance (points or wallet) for every unit of money spent. - Unit: Monetary unit per which the value is earned (must be ≥ 1). Example: `1` means "per €1 spent" - Value: Balance awarded per unit. Integer in `points` mode; decimal in `money` mode - Distribution: `total`, `individual_items`, or `individual_items_pro_rata` **Example use case (wallet mode):** Every 20 euros spent in Beverage you get 10 points. ### Direct value Awards a fixed, flat amount of balance or applies a fixed discount. - Value: Fixed amount. Integer in `points` mode; decimal in `money` mode - Distribution: `total`, `individual_items`, or `individual_items_pro_rata` - Bundle/group: Supported — can group products into bundle conditions. This only works if victory conditions has 1 group or less. If there are more than 1 group when creating a campaign with bundle effect true it will fail **Example use case:** Get 100 points for buying a product that costs 100 euros. ### Strikethrough Displays a promotional "crossed-out" price alongside the original price, applying a monetary discount and grants you the difference equivalent in points. Used to show perceived value. - `strikethrough_data`: A map of `{ product_id: promotional_price }` — one crossed-out price per product - Distribution: Always `individual_items` **Example use case:** Show "Was €29.99, Now €19.99" on product pages, without applying the discount in the transaction engine and grants you the difference equivalent in points. ### Combo price Sets a specific combined price for a group of products purchased together (bundle mechanics). - Value: The total price for the bundle. Must be > 0, decimals supported - Distribution: `total` or `individual_items_pro_rata` **Example use case:** Buy any 3 items from this category for €29.99 (regardless of individual prices) and grants you the difference equivalent in points. ### Distributions (summary) - `total`: The effect is applied as a single value to the transaction total - `individual_items`: The effect is applied to each qualifying line independently - `individual_items_pro_rata`: The total effect is distributed across qualifying lines proportionally by line value **Restrictions:** - `strikethrough` → `individual_items` only - `combo_price` → `total` or `individual_items_pro_rata` only - `formula` → `individual_items` only - Trigger / Custom Event / Challenge events → `total` only --- ### Effect limits & bundles - **Effect limit**: Maximum times this effect can apply per transaction. If not set or set to 0, applies every time conditions are met. - **Bundle/group**: Groups conditions into a bundle mechanic (e.g., buy A + B together) This only works if victory conditions has 1 group or less. If there are more than 1 group when creating a campaign with bundle effect true it will fail Effect limits and bundles are not available for Custom Event, Trigger, or Challenge events. ### Example Example of a campaign that awards 25% of each line amount as points. ```json { "key": "percentage", "type": "percentage", "value": 25, "distribution": "individual_items", "rule_group": false, "limits": 0 } ``` example: key: percentage type: percentage value: 25 distribution: individual_items rule_group: false limits: 0 rule_application: type: string description: > Advanced campaign application logic (JSON object). This part is used to define where the campaigns apply. **Important:** You cannot put more than 1 group in this case. ### Supported fields and operators - **Products and product categories** (`product_id`, `product_categories`): operator `in`, values are IDs or external IDs. - **Payment method** (`payment_method`): operator `in`, values are slugs of payment types (e.g., `card`, `cash`). - ** Additional costs** (`additional_costs`): operator `in`, values are slugs of additional costs (e.g., `shipping`, `handling`). **Important:** Contact us for more information about the supported fields and operators. ### Example Example of a campaign that applies to more than 1 product with the ID 5. ```json { "conditions": { "and": [ { "key": "cart_product_id", "field": "product_id", "bundle": 1, "values": [ 5 ], "grouped": true, "operator": "in", "conditions": [ { "field": "quantity", "value": 1, "operator": "gte" } ], "array_field": "lines" } ] } } ``` example: conditions: and: - key: cart_product_id field: product_id values: - 5 grouped: true operator: in conditions: - field: quantity value: 1 operator: eq array_field: lines stackability_properties: type: string description: Defines how the campaign stacks with others. enum: - stackability - highest_discount example: stackability priority: type: integer description: >- Priority of the campaign. Relevant for stackability. Required if stackability_properties is 'stackability' minimum: 1 example: 1 custom_entity_definition_id: type: integer description: Required if 'when' is 'after_create_custom_entity'. example: 100 CreateNewPointsCampaignRequestCouponParams: title: CreateNewPointsCampaignRequestCouponParams type: object description: >- This object defines the parameters related to coupons for a new campaign. It includes details such as the static code, availability, printing options, and other relevant attributes that determine how the coupons will be generated, distributed, and redeemed within the campaign. These parameters are essential for configuring the behavior of coupons in targeted campaigns or loyalty club promotions. **Important:** Required for targeted campaigns, all-members campaigns and loyalty club promotions that include a coupon. properties: static_code: type: string example: '{{rand_static_code}}' description: >- Required for all-members campaigns or loyalty club promotions that include a coupon. For targeted campaigns is optional **Important:** The static code can not be used more than once across all campaigns. If you attempt to use a static code that already exists in another campaign, the system will return an error indicating that the code is not unique. This ensures that each static code is associated with only one campaign, preventing conflicts and ensuring proper tracking of promotions. key: type: string example: UNIQUEKEY123 available_days: type: integer description: >- The number of days counting from the activation date until the coupon expires. **Required if you want to set relative periods for activation/expiration dates, campaign is targeted and available_delay_days is set.** Not required if you want to use fixed activation/expiration dates (taken from rule_params-> available_from and rule_params-> available_to). example: 90 available_delay_days: type: integer description: >- The number of days counting from the sent date until the coupon activates. **Required if you want to set relative periods for activation/expiration dates, campaign is targeted and available_days is set.** Not required if you want to use fixed activation/expiration dates (taken from rule_params-> available_from and rule_params-> available_to). example: 0 print_days: type: integer description: >- The total number of days between the print date and the completion of printing. By default 0. example: 90 print_delay_days: type: integer description: >- The total number of days between the activation date and the coupon is printed. By default 0. example: 0 printable: type: boolean description: if coupon is printable or not. False by default. example: true priority: type: integer description: >- Print priority if printable is true. By default, the priority is 1 for all coupons. A lower number indicates a higher priority, meaning that coupons with a priority of 1 will be printed before those with a priority of 2, and so on.' example: 1 external_id: type: string example: POS_COUPON_XYZ auto_select: type: boolean description: >- If true, coupon autoselected or auto-redeemable, depending on the system's integration type. Consequently, the customer is not required to perform any manual action to apply the discount. By default false, which means that the customer must manually select the coupon to apply the discount. example: true active: type: boolean description: >- Field accepted but ignored. Active value is taken from the rule_params -> active. Deprecated deprecated: true name: type: string description: >- Field accepted but ignored. Name value is taken from the rule_param -> name. Deprecated deprecated: true max_redemptions: type: integer description: >- Field accepted but ignored. max_redemptions value is taken from the rule_params-> once_limit. Deprecated deprecated: true available_from: type: string description: >- Field accepted but ignored. available_from value is taken from the rule_params-> available_from. Deprecated deprecated: true available_to: type: string description: >- Field accepted but ignored. available_to value is taken from the rule_params-> available_to. Deprecated deprecated: true CreateNewPointsCampaignRequest: title: CreateNewPointsCampaignRequest type: object properties: rule_params: type: object $ref: '#/components/schemas/CreateNewPointsCampaignRequestRuleParams' coupon_params: type: object $ref: '#/components/schemas/CreateNewPointsCampaignRequestCouponParams' ScoreTransactionOriginInfoActivity: title: ScoreTransactionOriginInfoActivity type: object description: Origin info when type = activity properties: id: type: integer format: int64 description: Unique identifier of the cart. example: 123456 code: type: string description: Code of the cart. example: ACT-123456 creation_date: type: string format: date-time description: Date and time of the cart. example: '2025-06-01T12:00:00Z' location_id: type: integer format: int64 description: Unique identifier of the location where the cart was created. example: 98765 total: type: number description: Total amount of the cart after applying all discounts. example: 100.5 original_total: type: number description: Original total amount of the cart before applying any discounts. example: 150.75 score: type: integer format: int64 description: Total amount of points win in a cart by all points campaigns example: 100 score_as_money: type: number description: >- Total amount of discount money won in this cart by all points campaigns example: 12.65 score_used: type: integer format: int64 description: Total amount of points used in a cart. example: 120 score_used_as_money: type: number description: Total amount of discount money (by points burned) used in a cart. example: 12.65 score_returned_from_customer: type: integer format: int64 description: Total amount of points that customer lost in a return. example: 12 score_returned_from_customer_as_money: type: number description: >- Total amount of discount money (considering points) that customer lost in a return. example: 1.25 score_returned_to_customer: type: integer format: int64 description: Total amount of points that customer win in a return. example: 12 score_returned_to_customer_as_money: type: number description: >- Total amount of discount money that customer win in a return by points returned. example: 1.25 total_scores_coupon_applied: type: number description: Total amount of scores won by coupons within the cart example: 116 total_scores_coupon_applied_as_money: type: number description: >- Total amount of money won by points coupons within the cart (total_scores_coupon_applied money equivalent) example: 1.16 total_discount_voucher_applied: type: number description: >- Total amount of discount money applied by targeted coupons within the cart example: 11.2 total_discount_applied: type: number description: >- Total amount of discount money applied by all discount campaigns within the cart example: 11.2 lines: type: array items: $ref: '#/components/schemas/LineActivity' description: | Array of lines. **Important** + The **`total`** amount of returned lines on the cart is adjusted after applying all relevant discounts, including those from promotional campaigns, vouchers, and any point-based discounts (cashback). + The original, unadjusted amount for each line item remains unchanged and is preserved in the **`original_total`** attribute. customer: type: array items: $ref: '#/components/schemas/Customer' description: > Provides supplementary information about the customer, relevant to the current purchase, only if the customer is identified in the transaction. effects: type: array items: $ref: '#/components/schemas/Effects' description: > This section provides a comprehensive overview of all loyalty effects applied to the purchase, encompassing both points-earning and discount-based campaigns. example: - rule_id: 2322 line: 1 rule_name: Product Discount type: discount effect_type: percentage distribution_type: individual_items select_customers: loyalty value: 100 - rule_id: 2323 line: -1 rule_name: Holiday Points Bonus type: points effect_type: direct_value distribution_type: total select_customers: all_customers value: 600 value_as_money: 6 available_from: '2025-06-01' available_to: '2026-05-30' - rule_id: 2324 line: 2 rule_name: Combo Meal Deal type: discount effect_type: combo_price distribution_type: individual_items_pro_rata select_customers: targeted value: 400 coupon_info: voucher_id: 111 voucher_code: 4344fjaa coupon_id: 122211 coupon_name: Combo Meal Deal - rule_id: 2325 line: 3 rule_name: Cashback Offer type: points effect_type: ratio distribution_type: total select_customers: loyalty value: 600 value_as_money: 6 available_from: '2025-06-01' available_to: '2026-05-30' - type: discount rule_id: 23224 rule_name: Discount 15% promo distribution_type: individual_items select_customers": targeted effect_type: rollback line: 6 value: 400 coupon_info: voucher_id: 222 voucher_code: sale190 coupon_id: 12311 coupon_name: Sales discount example - type: points effect_type: rollback rule_id: 12313 rule_name: Double points promo Weekends distribution_type: individual_items select_customers": targeted line: 7 value: -200 coupon_info: voucher_id: 223 voucher_code: doublepoints coupon_id: 12312 coupon_name: Double points campaign rejected_campaigns: type: array items: $ref: '#/components/schemas/RejectedCampaign' description: >- This attribute lists all campaigns , vouchers or coupons that were attempted to be applied to the cart but were rejected, along with the reasons for their rejection. invalid_coupons: type: array description: >- This attribute contains a list of all vouchers or coupons specified in `coupons_desired` that are either invalid or do not exist scores: type: array items: $ref: '#/components/schemas/ScoresResponse' description: > This section displays a detailed breakdown, line by line, of all loyalty points earned with the current purchase. coupons_desired: type: array description: >- 'Coupons sent in the request are those the user intended to apply. If the request included "selected", this field will list all coupons the customer selected and attempted to apply to the ticket. Note: This does not confirm the coupons were successfully applied. To see which coupons were actually applied, refer to the vouchers field.' attributes: type: object description: >- Attributes allow you to store additional data on activities. Uses the JSON Schema Form standard [link](https://json-schema.org/). > **⚠️ IMPORTANT:**
You must configure the schema in the platform.
If the schema is incorrect, the request will fail.

> **Configuration Path:** Configuration > Company > Custom Attributes **Allowed Data Types:** - **Primitives**: string, number, integer, boolean, null - **Arrays of primitives**: ALLOWED (e.g., `tags: ["vip", "premium"], scores: [1, 2, 3]`) - **Nested arrays**: NOT allowed (e.g., `[[1, 2], [3, 4]]`) - **Arrays of objects**: NOT allowed (e.g., `[{a: 1}, {b: 2}]`) - **Nested objects**: NOT allowed (e.g., `preferences: {newsletter: true}`) Attributes must be single-level only with a maximum of 50 attributes and 10KB total size. **Example:** ```json { "warranty_selected": true, "gift_wrap": false, "add_on_ids": [10, 20, 30], "special_instructions": "Handle with care", "product_condition": "new", "return_policy_applied": true } ``` example: warranty_selected: true gift_wrap: false add_on_ids: - 10 - 20 - 30 special_instructions: Handle with care product_condition: new return_policy_applied: true additional_costs: type: object description: >- It allows you to store additional costs associated with the cart. > **⚠️ IMPORTANT:**
You must configure the additional costs in the platform.
If an additional cost, sent in the request, does not exist in the platform, the request will fail.

> **Configuration Path:** Configuration > Company > Cart additional costs > **Considerations:** If there are any campaigns applying to a field of the additional costs, the value of that field will be adjusted after applying the campaign discount. The original value of the additional cost, before applying any discount, will be preserved in the `original_` field (e.g., if the additional cost field is `cost1`, the original value will be in `original_cost1`). **Limits:** - The JSON object must have only one level of keys. - Each value must be a number (float). **Example:** ```json { "cost1": 1.17, "cost2": 2.99, "original_cost1": 1.50, "original_cost2": 3.50 } ``` example: cost1: 1.17 cost2: 2.99 original_cost1: 1.5 original_cost2: 3.5 ScoreTransactionOriginInfoTransfer: title: ScoreTransactionOriginInfoTransfer type: object description: Origin info when type = transfer properties: from_customer_id: type: integer format: int64 description: Id of the customer transfering the points example: 9876666 to_customer_id: type: integer format: int64 description: Id of the customer receiving the points example: 67788876 comments: type: string description: Comments about the transfer example: Some comments ScoreTransactionOriginInfoSubtract: title: ScoreTransactionOriginInfoSubtract type: object description: Origin info when type = subtract properties: comments: type: string description: Comments about the subtraction example: Some comments ScoreTransactionOriginInfoTrigger: title: ScoreTransactionOriginInfoTrigger type: object description: Origin info when type = trigger properties: comments: description: Comment of the trigger type: string slug: description: Slug of the trigger that applied type: string RewardOriginInfoResponse: title: RewardOriginInfoResponse type: object properties: id: description: The ID of the reward type: integer name: type: string description: >- Name of the reward. If `multilingual` is enabled, the reward name will be returned in the language specified in the `Accept-Language` header type: type: string description: >- Type of the reward. The type of the reward could be any of the following: physical, digital, code, coupon, download, donation, voucher, free_delivery ScoreTransactionOriginInfoReward: title: ScoreTransactionOriginInfoReward type: object description: Origin info when type = reward properties: reward: description: Reward information $ref: '#/components/schemas/RewardOriginInfoResponse' ScoreTransactionOriginInfoExpirationOrActivation: title: ScoreTransactionOriginInfoExpirationOrActivation type: object description: Origin info when type = expiration or activation ScoreTransactionOriginInfoCustomEntity: title: ScoreTransactionOriginInfoCustomEntity type: object description: Origin info when type = custom_entity properties: score: type: integer format: int64 description: Total score won slug: description: Slug of the custom entity that applied type: string ChallengeOriginInfoResponse: title: ChallengeOriginInfoResponse type: object properties: id: description: The ID of the challenge type: integer name: type: string description: Name of the challenge ScoreTransactionOriginInfoChallenge: title: ScoreTransactionOriginInfoChallenge type: object description: Origin info when type = challenge properties: score: type: integer format: int64 description: Total score won challenge: description: Challenge information $ref: '#/components/schemas/ChallengeOriginInfoResponse' ScoreResponse: title: ScoreResponse type: object nullable: true description: Scores given by a transaction properties: loyalty_score_id: description: The ID of the loyalty score rule. type: integer format: int64 loyalty_score_name: description: >- The name of the loyalty score rule. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned in the name of the loyalty score. type: string score: description: Total points provided by the loyalty score rule in this transaction type: integer available_from: description: Date from which the points are available. Format yyyy-mm-dd type: string available_to: description: Date until which points are available. Format yyyy-mm-dd type: string example: loyalty_score_name: Base rule loyalty_score_id: 2 score: 32 available_from: '2023-07-10' available_to: '2023-12-10' GetListScoreTransactionsResponse: title: GetListScoreTransactionsResponse type: object properties: id: type: integer format: int64 example: 12 customer_id: type: integer format: int64 description: Id of the customer related with the transaction customer_code: description: Code of the customer related with the transaction (if present). type: string example: 33 amount: type: integer format: int64 description: Amount of points involved in the transaction. example: 100 pending_amount: type: integer format: int64 description: >- Amount of points involved in the transaction that are not active yet. example: 100 location_id: type: integer format: int64 nullable: true description: >- Id of the location where the transactions was made. For some types such as "expiration" will be null example: 775 type: description: >- Type of the transaction. Can be activity, transfer, trigger, expiration, reward, custom_entity, challenge, subtract, activation, redemption_reverted, tier type: string example: activity created_at: type: string description: 12-12 23:45:00' (string) - date time of the score creation example: 12-12 23:45:00 origin_info: description: >- Extra information about the transaction. It depends on the property type. oneOf: - $ref: '#/components/schemas/ScoreTransactionOriginInfoActivity' - $ref: '#/components/schemas/ScoreTransactionOriginInfoTransfer' - $ref: '#/components/schemas/ScoreTransactionOriginInfoSubtract' - $ref: '#/components/schemas/ScoreTransactionOriginInfoTrigger' - $ref: '#/components/schemas/ScoreTransactionOriginInfoReward' - $ref: >- #/components/schemas/ScoreTransactionOriginInfoExpirationOrActivation - $ref: '#/components/schemas/ScoreTransactionOriginInfoCustomEntity' - $ref: '#/components/schemas/ScoreTransactionOriginInfoChallenge' type: object scores: description: >- List of scores information given by the transaction grouped by loyalty score rule id (if applies) type: array items: $ref: '#/components/schemas/ScoreResponse' next_token_starts_after: description: >- Use this token to get the next page of results using the parameter starting_after example: 234 type: string Getcustomerscoresresponse: title: Getcustomerscoresresponse type: object properties: score: type: integer format: int64 description: Total score score_as_money: type: number description: Monetary equivalence of total score score_available: type: integer format: int64 description: Score available score_available_as_money: type: number nullable: true description: Monetary equivalence of score available currency: type: string nullable: true description: Monetary currency for the customer score_to_reach_cashback: type: integer format: int64 nullable: true description: Pending score needed to allow cashback (if thresholds are defined) money_to_spend_to_reach_cashback: type: number nullable: true description: Pending money needed to allow cashback (if thresholds are defined) score_threshold_cashback: type: integer format: int64 nullable: true description: Minimum score needed to allow cashback money_threshold_cashback: type: number nullable: true description: Minimum money needed to spend in order to allow cashback score_threshold_cashback_as_money: type: number nullable: true description: Monetary equivalence of the minimum score needed to allow cashback fraudulent: type: boolean nullable: true description: If the customer is fraudulent or not example: score: 100 score_as_money: 1 score_available: 80 score_available_as_money: 0.8 score_to_reach_cashback: 900 money_to_spend_to_reach_cashback: 90 score_threshold_cashback: 1000 money_threshold_cashback: 100 score_threshold_cashback_as_money: 10 currency: EUR fraudulent: false ScoreExpiring: title: ScoreExpiring properties: expiration_date: type: string description: >- Date of expiring scores considering the customer's country timezone. **Scores expire in the customer's timezone (not in UTC)**. Only date part is important here. Array is ordered by this field, sort desc. score_available: type: integer format: int64 description: Points available until the expiration date. score_available_as_money: type: number nullable: true description: >- The monetary value for the total points available until the expiration date. currency: type: string nullable: true description: >- Currency of the monetary value of the points available until the expiration date. GetCustomerExpiringScoresResponse: title: GetCustomerExpiringScoresResponse type: object properties: data: type: array items: $ref: '#/components/schemas/ScoreExpiring' example: '-data': - score_available: 50 score_available_as_money: 2 currency: EUR expiration_date: '2023-04-07T00:00:00Z' SubtractPointsFromACustomerRequest: title: SubtractPointsFromACustomerRequest required: - amount - comments type: object properties: customer_id: type: integer format: int64 description: Id of the customer example: 123 customer_code: description: >- Code of the customer to subtract points from. If `customer_id` is also sent, it will be used instead to find the customer. type: string example: a1b2c3d4 amount: type: integer format: int64 description: |- The user can remain in a negative status. The value must be between 1 and 2147483647. example: 100 comments: description: Comments about the action. type: string example: Subtract 100 from customer 123. SubtractPointsFromACustomerResponse: title: SubtractPointsFromACustomerResponse type: object properties: customer: $ref: '#/components/schemas/customer1' score_used: type: integer format: int64 description: Total Points of used in the subtraction. score: type: integer deprecated: true format: int64 description: >- Total Points of the customer after the subtraction. Could be a negative value. score_available: type: integer deprecated: true format: int64 description: Total available points of the customer after the subtraction. example: customer: id: 100005 code: b7f4-e4c9f549963a score: 2000 score_available: 1000 score_used: 100 score: 2000 score_available: 1000 ActivityRedeemRequest: title: ActivityRedeemRequest required: - amount type: object properties: activity_id: type: integer format: int64 description: >- ID of the activity. `activity_id` or `activity_code` are required and mutually exclusive. example: 12345 activity_code: type: string description: >- Code of the activity. `activity_id` or `activity_code` are required and mutually exclusive. example: a1b2c3d4 customer_id: type: integer format: int64 description: >- ID of the customer. `customer_id` or `customer_code` are required and mutually exclusive. example: 1234 customer_code: type: string description: >- Code of the customer. `customer_id` or `customer_code` are required and mutually exclusive. example: a1b2c3d4 location_id: type: integer format: int64 description: >- ID of the location. `location_id` or `location_code` are required and mutually exclusive. example: 12 location_code: type: string description: >- Code of the location. `location_id` or `location_code` are required and mutually exclusive. example: 12a amount: type: integer format: int64 description: The amount of scores to redeem example: 100 ActivityRedeemResponse: title: ActivityRedeemResponse type: object properties: customer: $ref: '#/components/schemas/customer1' score_used: type: integer format: int64 description: Total Points used in the redeem. score: type: integer deprecated: true format: int64 score_available: type: integer deprecated: true format: int64 example: customer: id: 100005 code: b7f4-e4c9f549963a score: 200 score_available: 100 score_used: 100 score: 200 score_available: 100 TransferRequestCustomerID: title: Transfer request with customer_id required: - score type: object properties: score: type: integer format: int64 description: Quantity of points to be transfered example: 24 from_customer_id: type: integer format: int64 description: >- Id of the customer transfering the points. `from_customer_id` or `from_customer_code` are required and mutually exclusive example: 9876666 to_customer_id: type: integer format: int64 description: >- Id of the customer receiving the points. `to_customer_id` or `to_customer_code` are required and mutually exclusive example: 67788876 country: type: string description: >- (deprecated) [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (It must be Capitals letters) example: es comments: type: string description: Comments about the transfer example: Some comments allow_partial: type: boolean example: true TransferRequestCustomerCode: title: Transfer request with customer_code required: - score type: object properties: score: type: integer format: int64 description: Quantity of points to be transfered example: 24 from_customer_code: type: string description: >- Code of the customer transfering the points. `from_customer_id` or `from_customer_code` are required and mutually exclusive example: '9876666' to_customer_code: type: string description: >- Code of the customer receiving the points. `to_customer_id` or `to_customer_code` are required and mutually exclusive example: '67788876' country: type: string description: >- (deprecated)[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (It must be Capitals letters) example: es comments: type: string description: Comments about the transfer example: Some comments allow_partial: type: boolean example: true TransferResponse: title: TransferResponse required: - from_customer_id - to_customer_id - score - comments - requested_scores type: object properties: from_customer_id: description: The customer ID that transfered the points type: integer format: int64 to_customer_id: description: The customer ID that received the points type: integer format: int64 from_customer_code: description: The customer Code that transfered the points type: string to_customer_code: description: The customer Code that received the points type: string score: description: The amount of transfered points type: integer format: int64 country: description: The country in which the score transfer occured type: string location_id: description: The location ID in which the score transfer occured type: string nullable: true comments: description: Optional comments about the score transfer type: string nullable: true requested_scores: description: The requested score amount to transfer type: integer format: int64 example: from_customer_id: 1150524070032999000 to_customer_id: 790178790032933400 from_customer_code: 1150524070032999000a to_customer_code: 790178790032933400a score: 100000 comments: A transfer of 10000 points requested_scores: 200000 Getcashbacksbasedonalocationresponse: title: Getcashbacksbasedonalocationresponse required: - cashback - currency type: object properties: cashback: type: number currency: type: string example: cashback: 0.005 currency: EUR Getcashbacksbasedonalocationresponse1: title: Getcashbacksbasedonalocationresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: invalid_request error: invalid location CashbackThresholdData: title: CashbackThresholdData type: object properties: score: type: integer format: int64 description: >- The minimum positive amount of scores a user needs to have to be able to obtain the cashback. country: type: string description: Country ISO_3166-2 code. example: ES money_representation: type: number format: float description: Points monetary equivalence. currency: type: string description: Currency ISO code of the company's default currency example: EUR CashbackThresholdDataList: title: CashbackThresholdData type: object properties: data: type: array items: $ref: '#/components/schemas/CashbackThresholdData' RewardResponse: title: RewardResponse type: object properties: id: description: The ID of the reward. type: integer example: 1001 name: description: >- The name of the reward. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. type: string example: Reward name description: description: >- The description of the reward. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. type: string points: type: integer description: The necessary points required to redeem the reward. example: 150 available_from: description: The date at which this reward will be available. type: string format: date example: '2019-02-01' available_to: description: The date until which this reward will be available. type: string format: date example: '2020-02-01' flexible_score_allowed: description: A flag indicating if the reward allows the score to be overwritten. type: boolean status: description: The status of the reward (active or inactive). type: string example: active countries: description: The countries in which this reward is available. type: array items: type: string extra_money: description: Extra money needed to redeem the reward. type: number format: float currency: description: >- The currency with which the reward must be redeemed. Must be in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) format. Must be present if extra_money is provided. type: string is_coupon: description: A flag indicating if the reward is a coupon. type: boolean image_url: description: The image (thumbnail) link of the reward. type: string image_file_name: description: The image (thumbnail) file name of the reward. type: string categories: type: array items: $ref: '#/components/schemas/RewardCategory' coupon: $ref: '#/components/schemas/Coupon' nullable: true type: description: Type name of the reward type: string example: physical partner: description: The partner related to the reward nullable: true $ref: '#/components/schemas/Partner' total_stock: description: >- Number that defines how many times a reward can be redeemed in total. Maximum number of stock or possible redemptions. If empty or null, redemptions are unlimited type: integer example: 1000 nullable: true can_redeem: description: |- Flag indicating if the customer can redeem the reward, based on: - Customer flagged as potentially fraudulent. - Points needed to redeem the reward versus points available for the customer. - Stock available for the reward. - Maximum redemptions quantity defined for each customer and reward. - Available for customer's tier. type: boolean nullable: true missing_redeem_conditions: description: >- **Only available when can_redeem=false** Represents the list of reasons why the customer cannot redeem the reward. Possible options: - When the reason is that the customer is flagged as potentially fraudulent, message will be "Your points are not available to use at this time". - When the reason is that the customer does not have enough points, message will be "Not enough points available to redeem - Missing Points: XXX". - When there is no more stock available for the reward, message will be “No more redemptions available for this reward”. - When there is no more redemptions available for the customer, message will be "There are no more redemptions available for this customer”. - When the reward is not available for customer's tier, message will be "Reward is not available for customer's tier". type: array items: type: string nullable: true redeem_chances: description: >- Define limitations regarding how many times this reward can be redeemed per customer. Options: - "always" - Unlimited redemptions quantity per customer - "num_total" - Total number of times - "num_day" - Total of times per day (natural) - "num_month" - Total of times per month - "num_year" - Total of times per year type: string redeem_times: description: >- Define limitations regarding how many times this reward can be redeemed per customer. Its related to the value defined in redeemed_chances. - if redeem_chances = "always" this field is not considered - E.g.: If redeem_times = 8 and redeem_chances = "num_year" it means the same customer may redeem this reward 8 times per year maximum type: integer available_stock: description: >- Number that defines the stock available based on total_stock and quantity of redemptions. It makes sense only if total_stock is available and has value. type: integer example: 50 nullable: true validity_duration_number: description: >- Number that defines the validity of the reward after redemption. Available when validity_duration_type = 'relative'. type: integer example: 3 validity_duration_unit_option: description: >- Unit that defines the validity of the reward after redemption. Available when validity_duration_type = 'relative'. Options are "days", "months", "years". type: string example: months validity_duration_date: description: >- Date that defines the validity of the reward after redemption. Available when validity_duration_type = 'fixed'. type: string example: '2024-02-01' validity_duration_type: description: >- Type to define validity of the reward. It can be 'fixed' or 'relative'. type: string example: fixed redemptions_quantity: description: >- Number of times this reward has been redeemed in total. When filtering by customer, it includes the number of times that the customer had redeemed this reward before. type: integer example: 1 redemption_type: description: |- Reward redemption type. Possible options: - 'manual' if the reward is available for direct redemption by the end customer using the /redeem endpoint. **Default value** - 'loyalty_rule' if the reward is linked to a loyalty rule award when conditions are met. These rewards are not directly redeemable by the end customer. type: string example: manual GetAListOfRewardsResponse: title: GetAListOfRewardsResponse type: object properties: data: type: array items: $ref: '#/components/schemas/RewardResponse' description: '' next_token_starts_after: type: string example: data: - id: 318 name: Green umbrella description: Exclusive green umbrella points: 100 flexible_score_allowed: true is_coupon: false status: active available_from: '2023-07-10' available_to: '2024-17-10' type: physical image_url: https://www.testimage.com/imagereward image_file_name: imagereward.png extra_money: 2.5 currency: EUR countries: - ES - IT - UK categories: - id: 3 name: Promotions taxonomy_slug: tags image_url: null - id: 4 name: Top buyers taxonomy_slug: customers image_url: null partner: id: 1 name: Airlines LG description: partnership with airline image_url: https://www.testImage.com/imagetest total_stock: 1000 can_redeem: true redeem_chances: num_year redeem_times: 1 available_stock: 10 validity_duration_number: 60 validity_duration_unit_option: days validity_duration_type: relative redemptions_quantity: 0 redemption_type: manual - id: 319 name: Red umbrella description: Exclusive red Umbrella points: 100 flexible_score_allowed: true available_from: '2023-01-01' available_to: '2023-12-31' status: active type: coupon image_url: null countries: - ES - AR - EE is_coupon: true categories: - id: 6 name: Promotions taxonomy_slug: tags image_url: null coupon: id: 123 key: 'discountkeyreferencing internal promo ' max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash affectation: activity features: - id: 1234 taxonomy_slug: a_slug product_ids: - 5 - 11 total_stock: 1000 can_redeem: false missing_redeem_conditions: - - 'Not enough points available to redeem - Missing Points: 60' redeem_chances: num_total redeem_times: 5 available_stock: 980 validity_duration_number: 3 validity_duration_unit_option: days validity_duration_date: '2023-12-31' validity_duration_type: fixed redemptions_quantity: 1 redemption_type: manual next_token_starts_after: '319' GetARewardByIDResponse: title: Get a reward by ID type: object properties: id: description: The ID of the reward. type: integer example: 1001 name: description: The name of the reward. type: string example: Reward name description: description: The description of the reward. type: string points: type: integer description: The necessary points required to redeem the reward. example: 150 available_from: description: The date at which this reward will be available. type: string format: date example: '2019-02-01' available_to: description: The date until which this reward will be available. type: string format: date example: '2020-02-01' flexible_score_allowed: description: A flag indicating if the reward allows the score to be overwritten. type: boolean status: description: The status of the reward (active or inactive). type: string example: active countries: description: The countries in which this reward is available. type: array items: type: string extra_money: description: Extra money needed to redeem the reward. type: number format: float currency: description: >- The currency with which the reward must be redeemed. Must be in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) format. Must be present if extra_money is provided. type: string is_coupon: description: A flag indicating if the reward is a coupon. type: boolean image_url: description: The image (thumbnail) link of the reward. type: string categories: type: array items: $ref: '#/components/schemas/RewardCategory' coupon: $ref: '#/components/schemas/Coupon' nullable: true type: description: Type name of the reward type: string example: physical partner: description: The partner related to the reward nullable: true $ref: '#/components/schemas/Partner' total_stock: description: >- Number that defines how many times a reward can be redeemed in total. Maximum number of stock or possible redemptions. If empty or null ,redemptions are unlimited type: integer example: 1000 nullable: true redeem_chances: description: >- Define limitations regarding how many times this reward can be redeemed per customer. Options: - "always" - Unlimited redemptions quantity per customer - "num_total" - Total number of times - "num_day" - Total of times per day (natural) - "num_month" - Total of times per month - "num_year" - Total of times per year type: string redeem_times: description: >- Define limitations regarding how many times this reward can be redeemed per customer. Its related to the value defined in redeemed_chances. - if redeem_chances = "always" this field is not considered - E.g.: If redeem_times = 8 and redeem_chances = "num_year" it means the same customer may redeem this reward 8 times per year maximum type: integer validity_duration_number: description: >- Number that defines the validity of the reward after redemption. Available when validity_duration_type = 'relative'. type: integer example: 3 validity_duration_unit_option: description: >- Unit that defines the validity of the reward after redemption. Available when validity_duration_type = 'relative'. type: string example: months validity_duration_date: description: >- Date that defines the validity of the reward after redemption. Available when validity_duration_type = 'fixed'. type: string example: '2024-02-01' validity_duration_type: description: >- Type to define validity of the reward. It can be 'fixed' or 'relative'. type: string example: fixed redemptions_quantity: description: >- Number of times this reward has been redeemed in total. When filtering by customer, it includes the number of times that the customer had redeemed this reward before. type: integer example: 1 can_redeem: description: |- Flag indicating if the customer can redeem the reward, based on: - Customer flagged as potentially fraudulent. - Points needed to redeem the reward versus points available for the customer. - Stock available for the reward. - Maximum redemptions quantity defined for each customer and reward. - Available for customer's tier. type: boolean nullable: true missing_redeem_conditions: description: >- **Only available when can_redeem=false** Represents the list of reasons why the customer cannot redeem the reward. Possible options: - When the reason is that the customer is flagged as potentially fraudulent, message will be "Your points are not available to use at this time". - When the reason is that the customer does not have enough points, message will be "Not enough points available to redeem - Missing Points: XXX". - When there is no more stock available for the reward, message will be “No more redemptions available for this reward”. - When there is no more redemptions available for the customer, message will be "There are no more redemptions available for this customer”. - When the reward is not available for customer's tier, message will be "Reward is not available for customer's tier". type: array items: type: string nullable: true redemption_type: description: |- Reward redemption type. Possible options: - 'manual' if the reward is available for direct redemption by the end customer using the /redeem endpoint. **Default value** - 'loyalty_rule' if the reward is linked to a loyalty rule award when conditions are met. These rewards are not directly redeemable by the end customer. type: string example: manual example: id: 319 name: Red umbrella description: Exclusive red Umbrella points: 100 flexible_score_allowed: true available_from: '2023-01-01' available_to: '2023-12-31' type: coupon status: active image_url: https://www.testimage.com/imagereward countries: - ES - UY - AR is_coupon: true categories: - id: 6 name: Promotions taxonomy_slug: tags image_url: null coupon: id: 123 key: 'discountkeyreferencing internal promo ' max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash affectation: activity features: - id: 1234 taxonomy_slug: a_slug product_ids: - 5 - 11 partner: id: 1 name: Airlines LG description: partnership with airline image_url: null extra_money: 2.5 currency: EUR total_stock: 1000 redeem_chances: num_total redeem_times: 5 validity_duration_number: 60 validity_duration_unit_option: days validity_duration_type: relative redemptions_quantity: 1000 can_redeem: true rdemption_type: manual RedeemARewardRequest: title: RedeemARewardRequest required: - location_id - location_code - customer_id - customer_code type: object properties: location_id: type: integer format: int64 description: >- Id of the location related to the reward redemption. `location_id` OR `location_code` are **required** and mutually exclusive. example: 21 location_code: type: string description: >- Code of the location related to the reward redemption. `location_id` OR `location_code` are **required** and mutually exclusive. example: AAHY79212 customer_id: type: integer format: int64 description: >- ID of the customer, is mutually exclusive to `associate_id` and `customer_code`. example: 8223 customer_code: type: string description: >- Code of the customer, is mutually exclusive to `associate_id` and `customer_id`. example: 8223a associate_id: type: integer format: int64 description: >- ID of the associate, is mutually exclusive to `customer_id` and `customer_code`. example: 123 score_overwrite: type: integer format: int64 description: >- Score value to overwrite the original reward score. If no value, original score needed to redeem the reward will be used and subtracted from the customer balance. example: 200 process_actions: type: boolean description: >- With a true value and in case that the reward has an associated coupon assigns a voucher to the client. example: false source: type: string description: |- source of the redemption. Possible values are: - "api", when the redemption is made through the API - "customer_service", when the redemption is made through the LG platform (customer profile) - "app", when the redemption is made through the LG white label app - "custom_entity", when the redemption is made through reward awarded for a custom entity campaign - "challenge", when the redemption is made through reward awarded for a challenge completed - "tier", when the redemption is made through reward awarded for a tier reached example: api RedeemARewardResponse: title: RedeemARewardResponse required: - score - score_available - redemption_id type: object properties: customer: $ref: '#/components/schemas/customer1' score_used: type: integer format: int64 description: Total Points used in the redeem. score: description: Total points of the customer after redeeming the reward. type: integer deprecated: true format: int64 score_available: description: Total available score of the customer after redeeming the reward. deprecated: true type: integer format: int64 redemption_id: description: ID of the redemption type: integer format: int64 code: description: Unique code assigned for the redemption (for rewards type = "Code") type: string example: customer: id: 100005 code: b7f4-e4c9f549963a score: 100 score_available: 60 score_used: 100 score: 100 score_available: 60 redemption_id: 12032 code: 8234ABR RedemptionResponse: title: RedemptionResponse type: object properties: id: type: integer format: int64 description: ID of the redemption created_at: type: string description: Timestamp of the redemption example: '2024-02-01 16:36:05' customer_id: type: integer format: int64 description: ID of the customer that redeemed customer_code: type: string description: customer_code of the customer that redeemed location_id: type: integer format: int64 description: ID of the location where the redemption was done reward_id: type: integer format: int64 description: ID of the reward redeemed score_expense: type: integer format: int64 description: Points spent on the redemption code: type: string description: >- Unique code assigned for the redemption (for rewards type = code or type = digital) origin_type: type: string description: >- Origin of the redemption to understand where it comes from. This field will not be included in the response if the reward is a manual redemption by the end customer. Possible values: - custom_entity: If the source of the reward was the award of a loyalty rule associated with a custom entity. - challenge: if the reward origin was the award of a loyalty rule associated with the completion of a challenge - upcoming: Trigger (If the source of the reward was the award of a loyalty rule associated with a trigger) and purchase (If the source of the reward was the award of a loyalty rule associated with a purchase.) origin_id: type: string description: >- Additional information about the origin_type. This field will not be included in the response if the reward is a manual redemption by the end customer. Possible values: - custom_entity_slug: If the reward comes from a custom entity. (origin_type = custom_entity) - challenge_id: If the reward is granted for winning a challenge. (origin_type = challenge) - activity_id: If the reward originates from a ticket purchase. (origin_type = purchase) - UPCOMING - trigger_slug: If the reward is earned through a trigger. (origin_type = trigger) - UPCOMING loyalty_rule_id: type: string description: >- ID of the loyalty rule applicable to this redemption. This field will not be included in the response if the reward is a manual redemption by the end customer. status: type: string description: >- Status of the redemption. Possible options are 'available' (default value) and 'reverted' (when the redemption has been reverted) status_detail: type: string description: >- When the redemption status is 'reverted', The reason for the reversal is shown here for clarity. source: type: string description: >- Source of the redemption to understand where it comes from. Possible values are: - "api", when the redemption is made through the API - "customer_service", when the redemption is made through the LG platform (customer profile) - "app", when the redemption is made through the LG white label app. - "custom_entity", when the redemption is made through reward awarded for a custom entity campaign - "challenge", when the redemption is made through reward awarded for a challenge completed - "tier", when the redemption is made through reward awarded for a tier reached example: api Getalistofredemptionsresponse: title: GetAListOfRedemptionsResponse type: object properties: data: type: array items: $ref: '#/components/schemas/RedemptionResponse' description: '' next_token_starts_after: type: string RevertARedemptionRequest: title: RevertARedemptionRequest required: - status_detail type: object properties: status_detail: type: string description: >- Information about the reason of the redemption rollback. Max length: 255 characters example: The item is out of stock RevertARedemptionResponse: title: RevertARedemptionResponse type: object properties: redemption_id: type: integer format: int64 description: ID of the redemption status: type: string description: Status of the redemption - 'reverted' status_detail: type: string description: The reason for the reversal is shown here for clarity. ChallengePrize: title: ChallengePrize type: object properties: type: type: string description: >- Type of award. Possible options: "points", "reward", "discount", "coupon" for coupon server logic coupon_info: type: object description: >- Information about the coupon that the customer might win if the challenge is completed. Available when type = "coupon" and coupon server logic is enabled. properties: coupon_id: type: integer format: int64 description: The ID of the coupon example: 4322211 coupon_name: type: string description: The name of the coupon example: 10% off on beverages coupon_description: type: string description: The description of the coupon example: Get 10% off on all beverages for the next 7 days rule_id: type: integer format: int64 description: The ID of the loyalty rule related to the prize example: 12345 rule_name: type: string description: >- The name of the loyalty rule related to the prize. If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. example: Beverage discount rule rule_effects: type: string description: | Advanced campaign effects (JSON object). Supported effect types depends on the type of prize. Discount includes: - **percentage** → applies a discount percentage on ticket/cart lines. - **direct_value** → fixed amount of discount applied. - **ratio** → Every x monetary unit you get a x discount (e.g. for every 20 euros spent in Beverage you get €1 of discount). - **strikethrough** → replaces product final price by discounted price (unit-based). - **combo_price** → sets a final price for a group of products (e.g. 2x1, 3x2, packs). - **informative** → no monetary effect; displays an informational message. Points include: - **percentage** → applies a promotion percentage on ticket/cart lines. - **direct_value** → fixed amount of points applied. - **ratio** → Every x monetary unit you get a x amount of points/wallet (e.g. for every 20 euros spent in Beverage you get 10 points). - **strikethrough** → replaces product final price by discounted price (unit-based) and grants you the difference equivalent in points. - **combo_price** → sets a final price for a group of products (e.g. 2x1, 3x2, packs) and grants you the difference equivalent in points. - **informative** → no monetary effect; displays an informational message. Distribution modes supported: - `total` → applies to total ticket. - `individual_items` → applies to each impacted line individually. - `individual_items_pro_rata` → prorates total effect across impacted lines. ### Example ```json { "key": "percentage", "type": "percentage", "value": 25, "distribution": "individual_items" } ``` example: >- {"key": "percentage", "type": "percentage", "value": 25, "distribution": "individual_items" } ChallengeLevel: title: ChallengeLevel type: object properties: level: type: integer format: int64 description: Level number name: type: string description: Name for the challenge level threshold: type: number description: Value of the attribute needed to reach to win the level reached: type: boolean description: >- When filtering by a customer: true if the level has been reached by the customer, false if not won_at: type: string description: >- When reached equals true, this is the datetime when the challenge level was reached by the customer. Time UTC. Format: yyyy-mm-ddThh:mm:ssZ prizes: type: array description: >- **Only for customer using the new engine version. For old version, the prizes are shown in awards object.** Information about the prizes that the customer might win if the challenge is completed. It can be points, reward, discount or coupon (if coupon server logic is enabled). items: $ref: '#/components/schemas/ChallengePrize' ChallengeResponse: title: ChallengeResponse type: object properties: id: description: The ID of the challenge type: integer name: type: string description: Name of the challenge description: type: string description: Description of the challenge status: type: string description: Status of the challenge (active or inactive) customer_attribute_id: type: integer description: Id of the customer attribute related to the challenge countries: type: array description: Countries where the challenge is available available_from: description: The date at which this challenge will be available type: string example: '2023-02-01' available_to: description: The date until which this challenge will be available type: string example: '2024-02-01' display_from: description: The date at which this challenge will be displayed type: string example: '2023-01-15' display_to: description: The date until which this challenge will be displayed type: string example: '2024-02-15' challenge_type: description: Type name of the challenge type: string example: Sports partner: description: The partner related to the challenge nullable: true $ref: '#/components/schemas/Partner' image_url: description: The image link of the challenge type: string image_file_name: description: The image file name of the challenge type: string open_to_all: description: >- If true, customers do not need to register for the challenge to participate. All customers participate in the challenge by default (depending on the challenge definition regarding country and customer attribute). type: boolean max_enrollments: description: >- Maximum number of enrollments allowed for the challenge. Makes sense if open_to_all is set to false and there are limits defined for enrollments number. type: integer current_enrollments: description: >- Number of current enrollments for the challenge (only informed when open_to_all is set to false). Available enrollments = max_enrollments - current_enrollments type: integer attribute_data_period_type: description: >- Period of calculation for the attribute defined for the challenge. Options: current_week, current_month, current_year, current_quarter, relative_days, relative_months type: string attribute_period_from: description: >- The start calculation date for the period of the attribute defined for the challenge. For example, if attribute_data_period_type = current_week, this value corresponds to the date of the Monday on which the current week started. **Important:** If the challenge has not started yet (available_from > current date), this value will be equal to available_from value. Not applicable if attribute_data_period_type = relative_days or relative_months. type: string example: '2023-02-01' attribute_period_to: description: >- The end calculation date for the period of the attribute defined for the challenge. For example, if attribute_data_period_type = current_week, this value corresponds to the date of the Sunday on which the current week ended. **Important:** If the challenge has not started yet (available_from > current date), this value will be equal to available_to value. Not applicable if attribute_data_period_type = relative_days or relative_months. type: string example: '2023-02-08' attribute_relative_value: description: >- Only applicable if attribute_data_period_type = relative_days or relative_months. It corresponds to the value defined for the attribute of the challenge. type: integer structure: type: array items: $ref: '#/components/schemas/ChallengeLevel' description: The different levels of which a challenge can be reached and won example: - id: 11 name: Run more this month description: Get extra points for running more this month! status: active customer_attribute_id: 2 countries: - ES - IT - UK available_from: '2023-07-10' available_to: '2024-12-31' display_from: '2023-07-01' display_to: '2025-01-15' challenge_type: Sports image_url: https://www.testimage.com/imagechallenge image_file_name: imagechallenge.png partner: id: 1 name: Airlines LG description: partnership with airline image_url: https://www.testImage.com/imagetest open_to_all: false max_enrollments: 1000 current_enrollments: 190 attribute_data_period_type: current_week attribute_period_from: '2024-02-26' attribute_period_to: '2024-03-03' structure: - level: 1 name: Run 60 kms threshold: 60 - id: 12 name: Spend more this week and get extra points description: If you spend more than 100 euros this week earn 1000 extra points status: active customer_attribute_id: 3 countries: - ES available_from: '2023-07-10' available_to: '2024-12-31' display_from: '2023-07-01' display_to: '2025-01-15' challenge_type: Sports image_url: https://www.testimage.com/imagechallenge image_file_name: imagechallenge.png open_to_all: true attribute_data_period_type: relative_months attribute_relative_value: 1 structure: - level: 1 name: Run 60 kms threshold: 60 GetAListOfChallengesResponse: title: GetAListOfChallengesResponse' type: object properties: data: type: array items: $ref: '#/components/schemas/ChallengeResponse' description: '' next_token_starts_after: type: string example: data: - id: 11 name: Run more this week description: Get extra points for running more this week! status: active customer_attribute_id: 2 countries: - ES - IT - UK available_from: '2024-01-01' available_to: '2024-12-31' display_from: '2023-12-15' display_to: '2025-01-15' challenge_type: Non-sports image_url: https://www.testimage.com/imagechallenge image_file_name: imagechallenge.png open_to_all: false max_enrollments: 1700 current_enrollments: 220 attribute_data_period_type: current_week attribute_period_from: '2024-02-26' attribute_period_to: '2024-03-03' structure: - level: 1 name: Run 60 kms threshold: 60 - id: 12 name: Spend more this week and get extra points description: If you spend more than 100 euros this week earn 1000 extra points status: active customer_attribute_id: 3 countries: - ES available_from: '2023-07-10' available_to: '2024-10-17' display_from: '2023-07-01' display_to: '2024-11-01' challenge_type: Sports image_url: https://www.testimage.com/imagechallenge image_file_name: imagechallenge.png open_to_all: true attribute_data_period_type: relative_months attribute_relative_value: 1 partner: id: 1 name: Airlines LG description: partnership with airline image_url: https://www.testImage.com/imagetest structure: - level: 1 name: Spend more than 100 euros threshold: 100 next_token_starts_after: true@101 GetAChallengeByIDResponse: title: Get a challenge by ID type: object properties: data: type: array items: $ref: '#/components/schemas/ChallengeResponse' example: id: 11 name: Run more this week description: Get extra points for running more this week! status: active customer_attribute_id: 2 countries: - ES - IT - UK available_from: '2023-07-10' available_to: '2024-12-31' display_from: '2023-07-01' display_to: '2025-01-15' challenge_type: Sports image_url: https://www.testimage.com/imagechallenge image_file_name: imagechallenge.png partner: id: 1 name: Airlines LG description: partnership with airline image_url: https://www.testImage.com/imagetest open_to_all: false max_enrollments: 1000 current_enrollments: 190 attribute_data_period_type: current_week attribute_period_from: '2024-02-26' attribute_period_to: '2024-03-03' structure: - level: 1 name: Run 60 kms threshold: 60 ChallengeAward: title: ChallengeAward type: object properties: amount: type: integer format: int64 description: >- The sum of the points, taking into account all loyalty rules that apply to the challenge and the customer. Available when type = "score". type: type: string description: >- Type of award. Possible options: "score", "reward", "discount", "coupon" for coupon server logic reward_id: type: integer format: int64 description: >- Id of the reward that the customer might win if the challenge is completed. Available when type = "reward" reward_name: type: string description: >- Name of the reward that the customer might win if the challenge is completed. Available when type = "reward". If multilanguage is enabled for the company, language of the "Accept-Language" header will be returned. loyalty_score_id: type: integer format: int64 description: The ID of the loyalty score rule related to the award CustomerChallengeResponse: title: CustomerChallengeResponse type: object properties: id: type: integer format: int64 description: Identifier of the challenge name: type: string description: Name of the challenge description: type: string description: Description of the challenge attribute_value: type: integer format: int64 description: >- Last calculated value of the customer attribute defined for the challenge. last_execution_time: type: string description: >- Last calculation execution datetime of the customer attribute defined for the challenge. Format: 2023-12-12 23:45:00 expires_at: type: string description: >- When reached= true. Expires at is the datetime when the challenge value is going to be reset. Time UTC. Format: yyyy-mm-ddThh:mm:ssZ available_from: description: The date at which this challenge will be available type: string example: '2023-02-01' available_to: description: The date until which this challenge will be available type: string example: '2024-02-01' display_from: description: The date at which this challenge will be displayed type: string example: '2023-01-15' display_to: description: The date until which this challenge will be displayed type: string example: '2024-02-15' challenge_type: description: Type name of the challenge type: string example: Sports partner: description: The partner related to the challenge nullable: true $ref: '#/components/schemas/Partner' image_url: description: The image link of the challenge type: string image_file_name: description: The image file name of the challenge type: string open_to_all: description: >- If true, customers do not need to register for the challenge to participate. All customers participate in the challenge by default (depending on the challenge definition regarding country and customer attribute). type: boolean max_enrollments: description: >- Maximum number of enrollments allowed for the challenge. Makes sense if open_to_all is set to false and there are limits defined for enrollments number. type: integer current_enrollments: description: >- Number of current enrollments for the challenge (only informed when open_to_all is set to false). Available enrollments = max_enrollments - current_enrollments type: integer to_reach_next_level_value: type: integer nullable: true description: Remaining value to reach the next level to_reach_next_level_name: type: string nullable: true description: Next level name to reach attribute_data_period_type: description: >- Period of calculation for the attribute defined for the challenge. Options: current_week, current_month, current_year, current_quarter, relative_days, relative_months type: string attribute_period_from: description: >- The start calculation date for the period of the attribute defined for the challenge. For example, if attribute_data_period_type = current_week, this value corresponds to the date of the Monday on which the current week started. **Important:** If the challenge has not started yet (available_from > current date), this value will be equal to available_from value. Not applicable if attribute_data_period_type = relative_days or relative_months. type: string example: '2023-02-01' attribute_period_to: description: >- The end calculation date for the period of the attribute defined for the challenge. For example, if attribute_data_period_type = current_week, this value corresponds to the date of the Sunday on which the current week ended. **Important:** If the challenge has not started yet (available_from > current date), this value will be equal to available_to value. Not applicable if attribute_data_period_type = relative_days or relative_months. type: string example: '2023-02-08' attribute_relative_value: description: >- Only applicable if attribute_data_period_type = relative_days or relative_months. It corresponds to the value defined for the attribute of the challenge. type: integer structure: type: array items: $ref: '#/components/schemas/ChallengeLevel' description: The different levels of which a challenge can be reached and won enrolled: description: >- True if the customer has enrolled to the challenge, false if not. For challenges with attribute open_to_all = true, the value of this field is always 'true' because the customer it is enrolled by default to the challenge. type: boolean awards: type: array description: >- **Only for customer using the old engine version. For new version, the awards are shown in prizes object.** Information about the awards that the customer might win if the challenge is completed. It can be points or reward items: $ref: '#/components/schemas/ChallengeAward' CustomerChallengesResponse: title: CustomerChallengesResponse type: array items: $ref: '#/components/schemas/CustomerChallengeResponse' example: data: - id: 11 name: Run more this month description: Get extra points for running more this month! attribute_value: 70 attribute_id: 10 last_execution_time: '2023-11-23T14:33:00Z' countries: - ES expires_at: '2023-11-25T14:33:00Z' available_from: '2023-07-10' available_to: '2024-12-31' display_from: '2023-07-01' display_to: '2025-01-15' challenge_type: Sports image_url: https://www.testimage.com/imagechallenge image_file_name: imagechallenge.png open_to_all: false max_enrollments: 1700 current_enrollments: 220 enrolled: true partner: id: 1 name: Airlines LG description: partnership with airline image_url: null attribute_data_period_type: current_week attribute_period_from: '2024-02-26' attribute_period_to: '2024-03-03' structure: - level: 1 name: Run 60 kms threshold: 60 reached: true won_at: '2023-11-23T14:33:00Z' prizes: - type: points rule_id: 12345 rule_name: 100 points extra effects: >- {"type": "direct_value", "value": 100, distribution": "total"} - type: coupon coupon_info: coupon_id: 4322211 coupon_name: 10% off on beverages coupon_description: Get 10% off on all beverages for the next 7 days - type: discount rule_id: 54321 rule_name: 15% discount on next purchase effects: >- {"type": "percentage", "value": 15, distribution": "total"} awards: - amount: 1000 type: score - reward_id: 12 reward_name: Free Netflix suscription for 3 months loyalty_score_id: 19099 type: reward - reward_id: 111 reward_name: 25% discount gym loyalty_score_id: 12222 type: reward - id: 12 name: Spend more this week and get extra points description: If you spend more than 100 euros this week earn 1000 extra points attribute_value: 70 attribute_id: 12 last_execution_time: '2023-11-21T15:33:00Z' open_to_all: false enrolled: true countries: - ES to_reach_next_level_value: 30 to_reach_next_level_name: Spend more than 100 euros attribute_data_period_type: relative_months attribute_relative_value: 1 structure: - level: 1 name: Spend more than 100 euros threshold: 100 reached: false awards: - amount: 100 type: score next_token_starts_after: false@101 EnrollAChallengeRequest: title: EnrollAChallengeRequest required: - customer_id - customer_code type: object properties: customer_id: type: integer format: int64 description: ID of the customer, is mutually exclusive to `customer_code`. example: 8223 customer_code: type: string description: Code of the customer, is mutually exclusive to `customer_id`. example: 8223agte enrolled_at: type: string description: Datetime of enrollment. UTC format yyyy-mm-ddThh:mm:ssZ example: '2024-02-23T12:00:00Z' ChallengeLevelSimplified: title: ChallengeLevelSimplified type: object properties: level: type: integer format: int64 description: Level number name: type: string description: Name for the challenge level threshold: type: number description: Value of the attribute needed to reach to win the level EnrollAChallengeResponse: title: EnrollAChallengeResponse type: object properties: id: type: integer format: int64 description: unique identifier of the transaction challenge_id: description: ID of the challenge type: integer format: int64 challenge_name: description: Name of the challenge type: string customer_id: description: ID of the customer type: integer format: int64 customer_code: description: Code of the customer type: string enrolled_at: description: Datetime of the enrollment example: '2024-02-23T12:00:00Z' type: string structure: type: array items: $ref: '#/components/schemas/ChallengeLevelSimplified' description: The different levels of which a challenge can be reached and won example: id: 1211 challenge_id: 35 challenge_name: Run more this month customer_id: 30 enrolled_at: '2024-02-23T12:00:00Z' structure: - level: 1 name: Run 60 kms threshold: 60 CreateaNewCouponrequest: title: CreateaNewCouponrequest required: - id - name - key type: object properties: id: type: integer format: int64 description: ID of the coupon in form of an integer example: 1234 name: type: string description: Name example: Coupon discount 50% description: type: string description: Description example: Discount on meat available_from: type: string description: Available from Date. example: '2016-01-01' available_to: type: string description: Available to Date. example: '2016-02-01' key: type: string description: >- This key is the code that your POS system will understand in order to apply a discount in a activity, we recomend this to be the same as the ID, but you can do as you please. Understand that this key is the one that will exist in the response when validating a VOUCHER related to this coupon. example: '1234' created_at: type: string description: DateTime of the creation of the coupon. example: '2016-01-01T12:00:00Z' location_ids: type: array items: type: integer format: int64 description: >- Array of location ids that the coupon belongs to. Do not specify this param if the coupon is available to ALL locations, only send this param if the coupon is available only in certain locations. priority: type: integer format: int64 description: Order in which the coupon will be printed. example: 1 external_id: type: string description: External ID example: '1' static_code: type: string description: Static code. example: - static_code active: type: boolean description: Is the coupon active? example: - false DeleteaCouponresponse: title: DeleteaCouponresponse required: - status type: object properties: status: type: string example: status: success UpdateaCouponrequest: title: UpdateaCouponrequest type: object properties: name: type: string description: Name example: - Coupon discount 50% description: type: string description: Description example: - Discount on meat available_from: type: string description: Available from Date. example: - '2016-01-01' available_to: type: string description: Available to Date. example: - '2016-02-01' created_at: type: string description: Created at Date. example: - '2015-12-01' key: type: string description: >- This key is the code that your POS system will understand in order to apply a discount in a ticket, we recomend this to be the same as the ID, but you can do as you please. Understand that this key is the one that will exist in the response when validating a VOUCHER related to this coupon. example: - '1234' priority: type: integer format: int64 description: Order in which the coupon will be printed. example: - 1 external_id: type: string description: External ID Used by PoS/TPV to relate coupons on her setup example: - '1' static_code: type: string description: Static code. example: - static_code active: type: boolean description: Is the coupon active? example: - false UpdateaCouponresponse: title: UpdateaCouponresponse required: - status type: object properties: status: type: string example: status: success status: title: status enum: - pending - printed - redeemed - cancelled type: string FeaturesVoucherList: title: FeaturesVoucherList type: object properties: taxonomy_slug: type: string id: type: integer format: int64 example: taxonomy_slug: marketing id: 32 discount_type: title: discount_type enum: - cash - percent type: string description: Type of applied discount example: cash affectation: title: affectation enum: - activity - attribute type: string description: Level to apply to discount example: activity Datum5: title: Datum5 required: - id - created_at - location_id - reward_id - score_expense type: object properties: id: type: integer format: int64 example: 1 description: Id of the voucher code: type: string example: '123234566' description: Code of the voucher available_from: type: string example: '2016-02-10' description: Start date of voucher validity available_to: type: string example: '2016-02-10' description: End date of voucher validity name: type: string example: Discount meat 50% description: Name of the coupon from which the voucher comes description: type: string example: Discount meat 50% extended description description: Voucher description image: type: string example: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png description: Coupon image image_original: type: string example: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/orignal/descarga.png description: Coupon original image key: type: string description: >- A key that can be user for your system to know how to apply the discount example: dis50meat status: $ref: '#/components/schemas/status' selected: type: boolean description: Indicates if the voucher is selected example: true available_redemptions: type: integer format: int64 description: Number of available redemptions for the voucher example: 1 max_redemptions: type: integer format: int64 description: Maximum number of allowed redemptions for the voucher example: 3 product_ids: type: array items: type: integer format: int64 description: IDs of product that this voucher applies to features: type: array items: $ref: '#/components/schemas/FeaturesVoucherList' description: >- List of features to which the voucher can be associated (e.g., merchandise category, geographic area, etc.) min_units: type: integer format: int64 description: >- Minimum number of products/services to be purchased to apply the discount example: 2 max_units: type: integer format: int64 description: >- Maximum number of products/services on which the discount can be applied example: 5 min_money: type: number description: Minimum of money to be able to apply the voucher. Allows float64 example: 10.5 max_money: type: number description: Maximum of money the voucher is appliable to. Allows float64 example: 5.5 points: type: integer format: int64 description: Amount of loyalty points associated to the voucher example: 100 points_money: type: number description: Amount of money associated to the loyalty points example: 0.95 has_points: type: boolean description: Indicates if the voucher allows loyalty points accumulation example: true discount_type: allOf: - $ref: '#/components/schemas/discount_type' - description: >- Type of applied discount ("percent" for percentage, "cash" for fixed value) example: cash discount: type: number description: Amount of applied discount (in percentage or fixed value) example: 5.5 affectation: allOf: - $ref: '#/components/schemas/affectation' - description: >- Discount application mode ("attribute" if the voucher is associated with a specific product/service, "cart" if the voucher is applied to the entire cart) example: activity frozen_redemptions: type: number description: Number of redemptions that have been made example: 1 cumulative: type: boolean description: >- Indicates if the voucher can be combined with other discounts/promotions example: false priority: type: integer format: int64 description: Mark the priority. example: 1 applies_to: type: string description: >- Specifies what the voucher applies to ("itself" if the voucher applies to itself, "other" if the voucher applies to other products/services) example: itself coupon_type: type: string description: Coupon type. Valid values -> (2x1, 3x2, 2nd_unit, min_units, custom) example: 3x2 purchased_affectation: type: string description: Purchased affectation. example: product purchased_features: type: array items: $ref: '#/components/schemas/FeaturesVoucherList' description: Purchased features. redemption_dates: type: array items: type: string format: date description: list of redemption dates payment_methods: type: array items: type: string description: >- Array of payment methods that may be used to trigger the extra discount payment_method_categories_1: type: array items: type: string description: >- Array of payment method category level 1 slugs (hierarchy_level = 1). Only present if there are payment methods at this hierarchy level payment_method_categories_2: type: array items: type: string description: >- Array of payment method category level 2 slugs (hierarchy_level = 2). Only present if there are payment methods at this hierarchy level payment_method_discount: type: number description: >- Extra discount to be applied when the payment method is one of the payment_methods payment_method_discount_type: type: string description: >- Type of the extra discount to be applied when the payment method is one of the payment_methods coupon_id: type: integer format: int64 example: 123 description: ID of the coupon associated with this voucher example: id: 1 key: discountkey available_from: '2016-01-01' available_to: '2016-01-31' description: Description code: '1234567891234' image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png image_original: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png available_redemptions: 1 frozen_redemptions: 1 name: Name max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 priority: 1 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 status: active has_points: true cumulative: true coupon_type: 3x2 affectation: activity applies_to: itself selected: false features: - id: 1234 taxonomy_slug: a_slug purchased_features: - id: 4567 taxonomy_slug: b_slug product_ids: - '5' - '11' purchased_product_ids: - '11' - '221' purchased_affectation: product location_ids: - 20 - 21 feature_locations: - name: feature name taxonomy_slug: taxonomy1 id: 101 - name: feature name 2 taxonomy_slug: taxonomy2 id: 202 redemption_dates: - '2016-01-01' - '2016-01-02' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash partner_description: Partner description 5 partner_id: 5 partner_name: Partner 5 coupon_id: 123 Getalistofvouchersresponse: title: Getalistofvouchersresponse type: object properties: data: type: array items: $ref: '#/components/schemas/Datum5' next_token_starts_after: type: string example: token Getalistofvouchersresponse1: title: Getalistofvouchersresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: invalid_request error: cannot parse id Getalistofselectedvouchersresponse: title: Getalistofselectedvouchersresponse required: - code - error type: object properties: code: type: string error: type: string example: code: invalid_request error: cannot parse id Getavoucherresponse: title: Getavoucherresponse type: object properties: id: type: integer format: int64 example: 1 description: Id of the voucher code: type: string example: '123234566' description: Code of the voucher available_from: type: string example: '2016-02-10' description: Start date of voucher validity available_to: type: string example: '2016-02-10' description: End date of voucher validity name: type: string example: Discount meat 50% description: Name of the coupon from which the voucher comes description: type: string example: Discount meat 50% extended description description: Voucher description image: type: string example: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png description: Coupon image image_original: type: string example: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/orignal/descarga.png description: Coupon original image key: type: string description: >- A key that can be user for your system to know how to apply the discount example: dis50meat status: $ref: '#/components/schemas/status' selected: type: boolean description: Indicates if the voucher is selected example: true available_redemptions: type: integer format: int64 description: Number of available redemptions for the voucher example: 1 max_redemptions: type: integer format: int64 description: Maximum number of allowed redemptions for the voucher example: 3 product_ids: type: array items: type: integer format: int64 description: IDs of product that this voucher applies to excluded_product_ids: type: array items: type: number description: Array of product ids that will be excluded from the coupon excluded_feature_pks: type: array items: type: object properties: taxonomy_slug: type: string description: The slug of the taxonomy the feature belongs to. id: type: number description: The ID of the feature to exclude. required: - taxonomy_slug - id description: Array of features that will be excluded from the coupon. features: type: array items: $ref: '#/components/schemas/FeaturesVoucherList' description: >- List of features to which the voucher can be associated (e.g., merchandise category, geographic area, etc.) min_units: type: integer format: int64 description: >- Minimum number of products/services to be purchased to apply the discount example: 2 max_units: type: integer format: int64 description: >- Maximum number of products/services on which the discount can be applied example: 5 min_money: type: number description: Minimum of money to be able to apply the voucher. Allows float64 example: 10.5 max_money: type: number description: Maximum of money the voucher is appliable to. Allows float64 example: 5.5 points: type: integer format: int64 description: Amount of loyalty points associated to the voucher example: 100 points_money: type: number description: Amount of money associated to the loyalty points example: 0.95 has_points: type: boolean description: Indicates if the voucher allows loyalty points accumulation example: true discount_type: allOf: - $ref: '#/components/schemas/discount_type' - description: >- Type of applied discount ("percent" for percentage, "cash" for fixed value) example: cash discount: type: number description: Amount of applied discount (in percentage or fixed value) example: 5.5 affectation: allOf: - $ref: '#/components/schemas/affectation' - description: >- Discount application mode ("attribute" if the voucher is associated with a specific product/service, "cart" if the voucher is applied to the entire cart) example: activity frozen_redemptions: type: number description: Number of redemptions that have been made example: 1 cumulative: type: boolean description: >- Indicates if the voucher can be combined with other discounts/promotions example: false priority: type: integer format: int64 description: Mark the priority. example: 1 applies_to: type: string description: >- Specifies what the voucher applies to ("itself" if the voucher applies to itself, "other" if the voucher applies to other products/services) example: itself coupon_type: type: string description: Coupon type. Valid values -> (2x1, 3x2, 2nd_unit, min_units, custom) example: 3x2 purchased_affectation: type: string description: Purchased affectation. example: product purchased_features: type: array items: $ref: '#/components/schemas/FeaturesVoucherList' description: Purchased features. payment_methods: type: array items: type: string description: >- Array of payment methods that may be used to trigger the extra discount payment_method_categories_1: type: array items: type: string description: >- Array of payment method category level 1 slugs (hierarchy_level = 1). Only present if there are payment methods at this hierarchy level payment_method_categories_2: type: array items: type: string description: >- Array of payment method category level 2 slugs (hierarchy_level = 2). Only present if there are payment methods at this hierarchy level payment_method_discount: type: number description: >- Extra discount to be applied when the payment method is one of the payment_methods payment_method_discount_type: type: string description: >- Type of the extra discount to be applied when the payment method is one of the payment_methods partner_description: type: string example: Partner description 5 description: Description of the partner partner_id: type: integer format: int64 example: 5 description: Id of the partner partner_name: type: string example: Partner 5 description: Name of the partner coupon_id: type: integer format: int64 example: 123 description: ID of the coupon associated with this voucher example: id: 1 key: discountkey available_from: '2016-01-01' available_to: '2016-01-31' description: Description code: '1234567891234' image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png image_original: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png available_redemptions: 1 frozen_redemptions: 1 name: Name max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 priority: 1 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 status: active has_points: true cumulative: true coupon_type: 3x2 affectation: activity applies_to: itself selected: false features: - id: 1234 taxonomy_slug: a_slug purchased_features: - id: 4567 taxonomy_slug: b_slug product_ids: - '5' - '11' excluded_product_ids: - '3' - '15' excluded_feature_pks: - '21' - '30' purchased_product_ids: - '10' - '220' purchased_affectation: product payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash partner_description: Partner description 5 partner_id: 5 partner_name: Partner 5 coupon_id: 123 Getavoucherresponse1: title: Getavoucherresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: invalid_request error: cannot parse id Vouchervalidationresponse: title: Vouchervalidationresponse type: object required: - key - code - available_redemptions - max_redemptions - min_money - max_money - min_units - max_units - discount - discount_type - affectation - cumulative - features - product_ids - priority properties: id: type: integer format: int64 example: 1 description: Id of the voucher code: type: string example: '123234566' description: Code of the voucher available_from: type: string example: '2016-02-10' description: Start date of voucher validity available_to: type: string example: '2016-02-10' description: End date of voucher validity name: type: string example: Discount meat 50% description: Name of the coupon from which the voucher comes description: type: string example: Discount meat 50% extended description description: Voucher description image: type: string example: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png description: Coupon image image_original: type: string example: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/orignal/descarga.png description: Coupon original image key: type: string description: >- A key that can be user for your system to know how to apply the discount example: dis50meat status: $ref: '#/components/schemas/status' selected: type: boolean description: Indicates if the voucher is selected example: true available_redemptions: type: integer format: int64 description: Number of available redemptions for the voucher example: 1 max_redemptions: type: integer format: int64 description: Maximum number of allowed redemptions for the voucher example: 3 product_ids: type: array items: type: integer format: int64 description: IDs of product that this voucher applies to excluded_product_ids: type: array items: type: number description: Array of product ids that will be excluded from the coupon excluded_feature_pks: type: array items: type: object properties: taxonomy_slug: type: string description: The slug of the taxonomy the feature belongs to. id: type: number description: The ID of the feature to exclude. required: - taxonomy_slug - id description: Array of features that will be excluded from the coupon. features: type: array items: $ref: '#/components/schemas/FeaturesVoucherList' description: >- List of features to which the voucher can be associated (e.g., merchandise category, geographic area, etc.) min_units: type: integer format: int64 description: >- Minimum number of products/services to be purchased to apply the discount example: 2 max_units: type: integer format: int64 description: >- Maximum number of products/services on which the discount can be applied example: 5 min_money: type: number description: Minimum of money to be able to apply the voucher. Allows float64 example: 10.5 max_money: type: number description: Maximum of money the voucher is appliable to. Allows float64 example: 5.5 points: type: integer format: int64 description: Amount of loyalty points associated to the voucher example: 100 points_money: type: number description: Amount of money associated to the loyalty points example: 0.95 has_points: type: boolean description: Indicates if the voucher allows loyalty points accumulation example: true discount_type: allOf: - $ref: '#/components/schemas/discount_type' - description: >- Type of applied discount ("percent" for percentage, "cash" for fixed value) example: cash discount: type: number description: Amount of applied discount (in percentage or fixed value) example: 5.5 affectation: allOf: - $ref: '#/components/schemas/affectation' - description: >- Discount application mode ("attribute" if the voucher is associated with a specific product/service, "cart" if the voucher is applied to the entire cart) example: activity frozen_redemptions: type: number description: Number of redemptions that have been made example: 1 cumulative: type: boolean description: >- Indicates if the voucher can be combined with other discounts/promotions example: false priority: type: integer format: int64 description: Mark the priority. example: 1 applies_to: type: string description: >- Specifies what the voucher applies to ("itself" if the voucher applies to itself, "other" if the voucher applies to other products/services) example: itself coupon_type: type: string description: Coupon type. Valid values -> (2x1, 3x2, 2nd_unit, min_units, custom) example: 3x2 purchased_affectation: type: string description: Purchased affectation. example: product purchased_features: type: array items: $ref: '#/components/schemas/FeaturesVoucherList' description: Purchased features. payment_methods: type: array items: type: string description: >- Array of payment methods that may be used to trigger the extra discount payment_method_categories_1: type: array items: type: string description: >- Array of payment method category level 1 slugs (hierarchy_level = 1). Only present if there are payment methods at this hierarchy level payment_method_categories_2: type: array items: type: string description: >- Array of payment method category level 2 slugs (hierarchy_level = 2). Only present if there are payment methods at this hierarchy level payment_method_discount: type: number description: >- Extra discount to be applied when the payment method is one of the payment_methods payment_method_discount_type: type: string description: >- Type of the extra discount to be applied when the payment method is one of the payment_methods coupon_id: type: integer format: int64 example: 123 description: ID of the coupon associated with this voucher example: id: 1 key: discountkey available_from: '2016-01-01' available_to: '2016-01-31' description: Description code: '1234567891234' image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png image_original: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png available_redemptions: 1 frozen_redemptions: 1 name: Name max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 priority: 1 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 status: active has_points: true cumulative: true coupon_type: 3x2 affectation: activity applies_to: itself selected: false features: - id: 1234 taxonomy_slug: a_slug purchased_features: - id: 4567 taxonomy_slug: b_slug product_ids: - '5' - '11' excluded_product_ids: - '3' - '15' excluded_feature_pks: - id: '21' taxonomy_slug: test_slug_1 - id: '30' taxonomy_slug: test_slug_2 purchased_product_ids: - '1' - '22' purchased_affectation: product payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash coupon_id: 123 Vouchervalidationresponse1: title: Vouchervalidationresponse1 required: - error - code type: object properties: error: type: string code: type: string example: error: >- Voucher not found, customer not found or voucher does not belongs to the customer code: voucher_not_found Voucher: title: Voucher required: - id - code type: object properties: id: type: string description: Id of the voucher to redeem. Required only if code is not informed example: 1234 code: type: string description: >- Code of the voucher ( **IMPORTANT**: Remember to use the **voucher_code** that you will find on the response for the **Voucher validation** endpoint, avoid always using the code obtained after barcode scaning or keyboard introduction even if most of the times will be the same as the voucher_code here mentioned ). Required only if id is not informed. example: '1234' discount: type: integer description: >- Discount amount in cents. Remember that if is a cancellation a negative amount should be specified. example: 1267 line_order: type: integer format: int64 description: Order of the line example: 1 product_id: type: integer format: int64 description: ID of the product example: 2 Redeemalistofvouchersrequest: title: Redeemalistofvouchersrequest required: - vouchers type: object properties: activity_id: type: integer format: int64 description: >- ID of the activity in form of an integer. **Mutually exclusive with `activity_code`**. example: 1234 activity_code: type: string description: >- Code of the activity associated. **Mutually exclusive with `activity_id`**. example: '456870' vouchers: type: array items: $ref: '#/components/schemas/Voucher' description: >- Array of the vouchers applied on this activity. This vouchers will be redeemed on the system so they're not used again. If the vouchers is used in more than one line use **line_order** or/and **product_id** to indicate in which one. Rollbackalistofvouchersrequest: title: Rollbackalistofvouchersrequest required: - vouchers type: object properties: vouchers: type: array minItems: 1 x-expanded: true items: oneOf: - title: Rollback by ID type: object additionalProperties: false required: - id properties: id: type: integer format: int64 description: >- ID of the voucher to rollback. Required only if code is not informed. minimum: 1 maximum: 9223372036854776000 example: 538294 - title: Rollback by code type: object additionalProperties: false required: - code - customer_id properties: code: type: string maxLength: 255 description: >- Code of the voucher to rollback. Required only if id is not informed. Must be used together with customer_id. example: CODE1 customer_id: type: integer format: int64 description: >- ID of the customer. Required when using code to identify the voucher. example: 1 description: >- Array of vouchers to rollback. Each voucher can be identified by id, or by code with customer_id (both required). When a voucher is rolled back, it returns to its previous state and the Available Redemptions count is increased by 1. example: - id: 538294 - id: 538295 - code: CODE1 customer_id: 1 - code: CODE2 customer_id: 2 VoucherV2Simple: title: VoucherV2Simple required: - code type: object properties: code: type: string description: Code of the voucher example: '1234' Updatealistofvoucherstoprintedstaterequest: title: Updatealistofvoucherstoprintedstaterequest required: - vouchers type: object properties: activity_id: type: integer format: int64 description: Activity which the voucher is associated. example: 238 vouchers: type: array items: $ref: '#/components/schemas/VoucherV2Simple' description: Array size must be below than 50. Printsalistofvouchersrequest: title: Printsalistofvouchersrequest required: - customer_id type: object properties: customer_id: type: integer format: int64 description: ID of the customer example: 345 size: type: integer format: int64 description: |- Number of vouchers minimum: 1 maximum: 10 example: 3 exclude_codes: type: array items: type: string description: >- List of voucher_codes, remember to use the voucher_code that you will find on the voucher_validation response, to exclude before print location_id: type: integer format: int64 description: >- ID of the location in form of an integer. It will print only vouchers from that location or without location example: 1 activity_id: type: integer format: int64 description: ID of the activity where the print happens example: 100005677 category: type: string description: Category of the voucher example: Summer exclude_ids: type: array items: type: integer format: int64 description: List of voucher ids to exclude before print debug: type: boolean description: |- If it is true the vouchers are not set as status = printed Default: `false` example: false Feature1: title: Feature1 required: - id - taxonomy_slug type: object properties: id: type: integer format: int64 taxonomy_slug: type: string example: id: 1 taxonomy_slug: test1 Printsalistofvouchersresponse: title: Printsalistofvouchersresponse type: object properties: code: type: string available_from: type: string available_to: type: string name: type: string description: type: string image: type: string key: type: string available_redemptions: type: integer format: int64 max_redemptions: type: integer format: int64 min_money: type: number max_money: type: number min_units: type: integer format: int64 max_units: type: integer format: int64 discount: type: number discount_type: type: string points: type: integer format: int64 points_money: type: number has_points: type: boolean affectation: type: string features: type: array items: $ref: '#/components/schemas/Feature1' description: '' image_original: type: string frozen_redemptions: type: integer format: int64 product_ids: type: array items: type: integer format: int64 excluded_product_ids: type: array items: type: integer format: int64 excluded_feature_pks: type: array items: type: object properties: taxonomy_slug: type: string description: The slug of the taxonomy the feature belongs to. id: type: number description: The ID of the feature to exclude. format: int64 required: - taxonomy_slug - id description: Array of features that will be excluded from the coupon. cumulative: type: boolean priority: type: integer format: int64 applies_to: type: string coupon_type: type: string purchased_affectation: type: string purchased_features: type: array items: $ref: '#/components/schemas/Feature1' payment_methods: type: array items: type: string description: >- Array of payment methods that may be used to trigger the extra discount payment_method_categories_1: type: array items: type: string description: >- Array of payment method category level 1 slugs (hierarchy_level = 1). Only present if there are payment methods at this hierarchy level payment_method_categories_2: type: array items: type: string description: >- Array of payment method category level 2 slugs (hierarchy_level = 2). Only present if there are payment methods at this hierarchy level payment_method_discount: type: number description: >- Extra discount to be applied when the payment method is one of the payment_methods payment_method_discount_type: type: string description: >- Type of the extra discount to be applied when the payment method is one of the payment_methods example: code: '123123123987987987' available_from: '2016-02-10' available_to: '2016-02-28' name: Discount meat 50% description: Discount meat 50% extended description image: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/thumbnail/descarga.png image_original: >- https://s3.amazonaws.com/loyal-guru-default/campaign_history_coupons/images/000/000/009/orignal/descarga.png key: dis50meat available_redemptions: 1 max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash points: 100 points_money: 0.95 has_points: true affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 3 product_ids: - 1 - 2 - 3 excluded_product_ids: - 3 - 15 excluded_feature_pks: - 21 - 30 cumulative: false priority: 1 applies_to: itself coupon_type: 3x2 purchased_affectation: product purchased_features: - id: 4567 taxonomy_slug: b_slug payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash Voucherselectionresponse: title: Voucherselectionresponse required: - code - available_from - available_to - name - description - key - image - status - selected - available_redemtions - cumulative - max_redemptions - min_money - max_money - min_units - max_units - discount - discount_type - affectation - features type: object properties: id: type: integer format: int64 code: type: string available_from: type: string available_to: type: string name: type: string description: type: string key: type: string image: type: string status: type: string selected: type: boolean available_redemtions: type: integer format: int64 cumulative: type: boolean max_redemptions: type: integer format: int64 min_money: type: number max_money: type: number min_units: type: integer format: int64 max_units: type: integer format: int64 discount: type: number discount_type: type: string affectation: type: string features: type: array items: $ref: '#/components/schemas/Feature1' description: '' frozen_redemptions: type: number priority: type: integer format: int64 applies_to: type: string purchased_affectation: type: string payment_methods: type: array items: type: string description: >- Array of payment methods that may be used to trigger the extra discount payment_method_categories_1: type: array items: type: string description: >- Array of payment method category level 1 slugs (hierarchy_level = 1). Only present if there are payment methods at this hierarchy level payment_method_categories_2: type: array items: type: string description: >- Array of payment method category level 2 slugs (hierarchy_level = 2). Only present if there are payment methods at this hierarchy level payment_method_discount: type: number description: >- Extra discount to be applied when the payment method is one of the payment_methods payment_method_discount_type: type: string description: >- Type of the extra discount to be applied when the payment method is one of the payment_methods coupon_id: type: integer format: int64 example: 123 description: ID of the coupon associated with this voucher example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: true available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash coupon_id: 123 Voucherselectionresponse1: title: Voucherselectionresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: voucher_not_found error: error get voucher {code} on company {company} Voucherdeselectionresponse: title: Voucherdeselectionresponse required: - code - available_from - available_to - name - description - key - image - status - selected - available_redemtions - cumulative - max_redemptions - min_money - max_money - min_units - max_units - discount - discount_type - affectation - features type: object properties: id: type: integer format: int64 code: type: string available_from: type: string available_to: type: string name: type: string description: type: string key: type: string image: type: string status: type: string selected: type: boolean available_redemtions: type: integer format: int64 cumulative: type: boolean max_redemptions: type: integer format: int64 min_money: type: number max_money: type: number min_units: type: integer format: int64 max_units: type: integer format: int64 discount: type: number discount_type: type: string affectation: type: string features: type: array items: $ref: '#/components/schemas/Feature1' description: '' frozen_redemptions: type: number priority: type: integer format: int64 applies_to: type: string purchased_affectation: type: string payment_methods: type: array items: type: string description: >- Array of payment methods that may be used to trigger the extra discount payment_method_categories_1: type: array items: type: string description: >- Array of payment method category level 1 slugs (hierarchy_level = 1). Only present if there are payment methods at this hierarchy level payment_method_categories_2: type: array items: type: string description: >- Array of payment method category level 2 slugs (hierarchy_level = 2). Only present if there are payment methods at this hierarchy level payment_method_discount: type: number description: >- Extra discount to be applied when the payment method is one of the payment_methods payment_method_discount_type: type: string description: >- Type of the extra discount to be applied when the payment method is one of the payment_methods coupon_id: type: integer format: int64 example: 123 description: ID of the coupon associated with this voucher example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: false available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash coupon_id: 123 Voucherdeselectionresponse1: title: Voucherdeselectionresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: voucher_not_found error: error get voucher {code} on company {company} Updatealistofvoucherstoselectedstaterequest: title: Updatealistofvoucherstoselectedstaterequest required: - vouchers type: object properties: vouchers: type: array items: $ref: '#/components/schemas/VoucherV2Simple' description: Array size must be below than 50. Voucherfreezeresponse1: title: Voucherfreezeresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: voucher_not_found error: error get voucher {code} on company {company} Voucherfreezeresponse: title: Voucherfreezeresponse required: - code - available_from - available_to - name - description - key - image - status - selected - available_redemtions - cumulative - max_redemptions - min_money - max_money - min_units - max_units - discount - discount_type - affectation - features type: object properties: id: type: integer format: int64 code: type: string available_from: type: string available_to: type: string name: type: string description: type: string key: type: string image: type: string status: type: string selected: type: boolean available_redemtions: type: integer format: int64 cumulative: type: boolean max_redemptions: type: integer format: int64 min_money: type: number max_money: type: number min_units: type: integer format: int64 max_units: type: integer format: int64 discount: type: number discount_type: type: string affectation: type: string features: type: array items: $ref: '#/components/schemas/Feature1' description: '' frozen_redemptions: type: number priority: type: integer format: int64 applies_to: type: string purchased_affectation: type: string payment_methods: type: array items: type: string description: >- Array of payment methods that may be used to trigger the extra discount payment_method_categories_1: type: array items: type: string description: >- Array of payment method category level 1 slugs (hierarchy_level = 1). Only present if there are payment methods at this hierarchy level payment_method_categories_2: type: array items: type: string description: >- Array of payment method category level 2 slugs (hierarchy_level = 2). Only present if there are payment methods at this hierarchy level payment_method_discount: type: number description: >- Extra discount to be applied when the payment method is one of the payment_methods payment_method_discount_type: type: string description: >- Type of the extra discount to be applied when the payment method is one of the payment_methods example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: true available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash Voucherunfreezeresponse: title: Voucherunfreezeresponse required: - code - available_from - available_to - name - description - key - image - status - selected - available_redemtions - cumulative - max_redemptions - min_money - max_money - min_units - max_units - discount - discount_type - affectation - features type: object properties: id: type: integer format: int64 code: type: string available_from: type: string available_to: type: string name: type: string description: type: string key: type: string image: type: string status: type: string selected: type: boolean available_redemtions: type: integer format: int64 cumulative: type: boolean max_redemptions: type: integer format: int64 min_money: type: number max_money: type: number min_units: type: integer format: int64 max_units: type: integer format: int64 discount: type: number discount_type: type: string affectation: type: string features: type: array items: $ref: '#/components/schemas/Feature1' description: '' frozen_redemptions: type: number priority: type: integer format: int64 applies_to: type: string purchased_affectation: type: string payment_methods: type: array items: type: string description: >- Array of payment methods that may be used to trigger the extra discount payment_method_categories_1: type: array items: type: string description: >- Array of payment method category level 1 slugs (hierarchy_level = 1). Only present if there are payment methods at this hierarchy level payment_method_categories_2: type: array items: type: string description: >- Array of payment method category level 2 slugs (hierarchy_level = 2). Only present if there are payment methods at this hierarchy level payment_method_discount: type: number description: >- Extra discount to be applied when the payment method is one of the payment_methods payment_method_discount_type: type: string description: >- Type of the extra discount to be applied when the payment method is one of the payment_methods example: id: 1312620 code: '1234' available_from: '2019-01-01' available_to: '2019-02-28' name: Name description: Description key: Key image: image url status: pending selected: false available_redemtions: 1 cumulative: true max_redemptions: 3 min_money: 10.2 max_money: 50.2 min_units: 3 max_units: 8 discount: 0.2 discount_type: cash affectation: activity features: - id: 1234 taxonomy_slug: a_slug frozen_redemptions: 0 priority: 1 applies_to: itself purchased_affectation: '' payment_methods: - cash - credit_card payment_method_categories_1: - bbva - ing - santander payment_method_categories_2: - '098230' - '23894' payment_method_discount: 0.2 payment_method_discount_type: cash Voucherunfreezeresponse1: title: Voucherunfreezeresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: voucher_not_found error: error get voucher {code} on company {company} GetVouchersExcludedProductsResponse: title: GetVouchersExcludedProductsResponse type: object properties: excluded_product_ids: type: array example: - 111 - 222 items: type: integer format: int64 excluded_product_category_ids: type: array example: - 111 - 222 items: type: integer format: int64 FeatureWithIdInput: title: FeatureWithIdInput type: object required: - id - taxonomy_slug properties: id: type: integer format: int64 description: ID of the feature. Allows int, max value 2147483647 example: 2 taxonomy_slug: type: string description: Taxonomy slug example: family FeatureWithCodeInput: title: FeatureWithCodeInput type: object required: - code - taxonomy_slug properties: code: type: string description: Code of the feature example: A_12345 taxonomy_slug: type: string description: Taxonomy slug example: family CreateaNewProductrequest: title: CreateaNewProductrequest required: - id - name type: object properties: id: type: integer format: int64 description: >- ID of the product in form of an integer(int64), maximum value: 9223372036854775807 example: 1234 name: type: string description: Name of the product example: Chicken breast description: type: string description: Description of the product example: Free run chicken breast code: type: string description: Code of the product example: 1234a margin: type: number description: Margin percent (0 to 1) of the product without taxes example: 0.11 price: type: number description: PVP of the product with taxes example: 11.99 cost: type: number description: product cost until it reaches the warehouse example: 10.23 tax: type: number description: Tax ratio (0 to 1) of the product example: 0.21 measurement_unit: type: string description: >- Type of unit of the quantity. Must be one of these: ( kg, g, l, m, u ) example: g status: type: string description: |- Status of the product, must be one of them: active inactive Default: active example: active custom1: type: string description: Custom value example: custom value 1 custom2: type: string description: Custom value example: custom value 2 custom3: type: string description: Custom value example: custom value 3 custom4: type: string description: Custom value example: custom value 4 custom5: type: string description: Custom value example: custom value 5 custom6: type: string description: Custom value example: custom value 6 custom7: type: string description: Custom value example: custom value 7 custom8: type: string description: Custom value example: custom value 8 features: type: array items: oneOf: - $ref: '#/components/schemas/FeatureWithIdInput' - $ref: '#/components/schemas/FeatureWithCodeInput' description: >- Array of features that the product belongs to. Each feature can be identified by either ID or code. example: id: 1234 name: Chicken breast description: Free run chicken breast code: 1234a margin: 0.11 price: 11.99 cost: 10.23 tax: 0.21 measurement_unit: g status: active features: - id: 2 taxonomy_slug: family FeatureWithCodeResponse: title: FeatureWithCodeResponse type: object required: - id - code - taxonomy_slug properties: id: type: integer format: int64 description: ID of the feature code: type: string description: Code of the feature taxonomy_slug: type: string description: Taxonomy slug CreateaNewProductresponse: title: CreateaNewProductresponse required: - id - name - description - code - price - margin - cost - tax - status - measurement_unit - custom1 - custom2 - custom3 - custom4 - custom5 - custom6 - custom7 - custom8 - features type: object properties: id: type: integer format: int64 name: type: string description: type: string code: type: string price: type: number margin: type: number cost: type: number tax: type: number status: type: string measurement_unit: type: string custom1: type: string custom2: type: string custom3: type: string custom4: type: string custom5: type: string custom6: type: string custom7: type: string custom8: type: string features: type: array items: oneOf: - $ref: '#/components/schemas/Feature1' - $ref: '#/components/schemas/FeatureWithCodeResponse' description: >- Array of features that the product belongs to. Each feature can be identified by either ID or code. example: id: 1234 name: Chicken description: Free run chicken code: p-1code price: 11.99 margin: 0.11 cost: 10.23 tax: 0.21 status: active measurement_unit: g custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: meat - id: 2 taxonomy_slug: fresh FeatureWithCode: title: FeatureWithCode required: - id - taxonomy_slug type: object properties: id: type: integer format: int64 code: type: string taxonomy_slug: type: string example: id: 1 code: 1_abc taxonomy_slug: test1 Getproductresponse: title: Getproductresponse required: - id - name - description - code - price - margin - cost - tax - status - measurement_unit - custom1 - custom2 - custom3 - custom4 - custom5 - custom6 - custom7 - custom8 - features type: object properties: id: type: integer format: int64 name: type: string description: type: string code: type: string price: type: number margin: type: number cost: type: number tax: type: number status: type: string measurement_unit: type: string custom1: type: string custom2: type: string custom3: type: string custom4: type: string custom5: type: string custom6: type: string custom7: type: string custom8: type: string features: type: array items: $ref: '#/components/schemas/FeatureWithCode' description: '' example: id: 1234 name: Chicken description: Free run chicken code: p-1code price: 11.99 margin: 0.11 cost: 10.23 tax: 0.21 status: active measurement_unit: g custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 code: 1_abc taxonomy_slug: meat - id: 2 code: 2_def taxonomy_slug: fresh UpdateaProductrequest: title: UpdateaProductrequest type: object properties: name: type: string description: Name of the product example: Chicken breast description: type: string description: Description of the product example: Free run chicken breast code: type: string description: Code of the product example: 1234a margin: type: number description: Margin percent (0 to 1) of the product without taxes example: 0.11 price: type: number description: PVP of the product with taxes example: 11.99 cost: type: number description: product cost until it reaches the warehouse example: 10.23 tax: type: number description: Tax ratio (0 to 1) of the product example: 0.21 measurement_unit: type: string description: >- Type of unit of the quantity. Must be one of these: ( kg, g, l, m, u ) example: g status: type: string description: |- Status of the product, must be one of them: active inactive Default: active example: active custom1: type: string description: Custom value example: custom value 1 custom2: type: string description: Custom value example: custom value 2 custom3: type: string description: Custom value example: custom value 3 custom4: type: string description: Custom value example: custom value 4 custom5: type: string description: Custom value example: custom value 5 custom6: type: string description: Custom value example: custom value 6 custom7: type: string description: Custom value example: custom value 7 custom8: type: string description: Custom value example: custom value 8 features: type: array items: oneOf: - $ref: '#/components/schemas/FeatureWithIdInput' - $ref: '#/components/schemas/FeatureWithCodeInput' description: >- Array of features that the product belongs to. Each feature can be identified by either ID or code. UpdateaProductresponse: title: UpdateaProductresponse required: - id - name - description - code - price - margin - cost - tax - status - measurement_unit - custom1 - custom2 - custom3 - custom4 - custom5 - custom6 - custom7 - custom8 - features type: object properties: id: type: integer format: int64 name: type: string description: type: string code: type: string price: type: number margin: type: number cost: type: number tax: type: number status: type: string measurement_unit: type: string custom1: type: string custom2: type: string custom3: type: string custom4: type: string custom5: type: string custom6: type: string custom7: type: string custom8: type: string features: type: array items: oneOf: - $ref: '#/components/schemas/Feature1' - $ref: '#/components/schemas/FeatureWithCodeResponse' description: >- Array of features that the product belongs to. Each feature can be identified by either ID or code. example: id: 1234 name: Chicken description: Free run chicken code: p-1code price: 11.99 margin: 0.11 cost: 10.23 tax: 0.21 status: active measurement_unit: g custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: meat - id: 2 taxonomy_slug: fresh CreateaNewTaxonomyrequest: title: CreateaNewTaxonomyrequest required: - name - slug type: object properties: name: type: string description: Name of the taxonomy example: Meat slug: type: string description: >- Slug of the taxonomy. The slug should be a short label for something, containing only letters, numbers, underscores or hyphens. example: meat UpdateaTaxonomyrequest: title: UpdateaTaxonomyrequest type: object properties: name: type: string description: Name of the taxonomy example: Dairy Products ParentFeature: title: ParentFeature type: object properties: id: type: integer format: int64 description: ID of the parent feature example: 1 taxonomy_slug: type: string description: Taxonomy slug of the parent feature example: section ParentFeatureWithCode: title: ParentFeatureWithCode type: object properties: code: type: string description: Code of the parent feature example: A_12345 taxonomy_slug: type: string description: Taxonomy slug of the parent feature example: section CreateaNewFeaturerequest: title: CreateaNewFeaturerequest oneOf: - title: Create Feature by ID description: Create a new feature using the feature ID type: object required: - id - name - slug properties: id: type: integer format: int64 description: ID of the feature in form of an integer example: 12345 name: type: string description: Name of the feature example: Chicken meat slug: type: string description: >- Slug of the feature. The slug should be a short label for something, containing only letters, numbers, underscores or hyphens. example: chicken_meat parent_features: type: array items: $ref: '#/components/schemas/ParentFeature' description: >- Array of parent features. The feature will be considereded as 'belonging to' all parent features. example: id: 12345 name: Chicken meat slug: chicken_meat parent_features: - id: 1 taxonomy_slug: section - title: Create Feature by Code description: Create a new feature using the feature code type: object required: - code - name - slug properties: code: type: string description: >- Code of the feature. `id` or `code` are required and mutually exclusive. example: A_12345 name: type: string description: Name of the feature example: Chicken meat slug: type: string description: >- Slug of the feature. The slug should be a short label for something, containing only letters, numbers, underscores or hyphens. example: chicken_meat parent_features: type: array items: $ref: '#/components/schemas/ParentFeatureWithCode' description: >- Array of parent features. The feature will be considereded as 'belonging to' all parent features. example: code: A_12345 name: Chicken meat slug: chicken_meat parent_features: - code: A_1 taxonomy_slug: section UpdateaFeaturerequestById: title: UpdateAFeatureRequestById type: object properties: name: type: string description: Name of the feature example: Chicken meat parent_features: type: array items: $ref: '#/components/schemas/ParentFeature' description: >- Array of parent features. The feature will be considereded as 'belonging to' all parent features. example: name: Chicken meat parent_features: - id: 1 taxonomy_slug: section UpdateaFeaturerequestByCode: title: UpdateAFeatureRequestByCode type: object properties: name: type: string description: Name of the feature example: Chicken meat parent_features: type: array items: $ref: '#/components/schemas/ParentFeatureWithCode' description: >- Array of parent features. The feature will be considereded as 'belonging to' all parent features. example: name: Chicken meat parent_features: - code: A_1 taxonomy_slug: section Feature: title: Feature type: object properties: id: type: integer format: int64 description: ID of the feature. Allows int, max value 2147483647 example: 2 taxonomy_slug: type: string description: Taxonomy slug example: family CreateaNewLocationrequest: title: CreateaNewLocationrequest required: - name - country type: object properties: id: type: integer format: int64 description: >- ID of the location in form of an integer. Mutually exclusive with `code`. example: 1234 code: type: string description: Code of the location. Mutually exclusive with `id`. example: 124AB name: type: string description: Name example: Local number 1234 postal_code: type: string description: Postal code example: '08110' address: type: string description: Address of the location example: Joan Miró address_extra: type: string description: Extra information about the address. example: '31' phone: type: string description: Phone example: '678513344' country: type: string description: >- Code of the location's country according to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (It must be Capital letters) example: ES currency: type: string description: >- Code of the location's currency according to the [ISO 4217](https://en.wikipedia.org/wiki/List_of_circulating_currencies)(It must be Capitals letters) example: EUR city: type: string description: City name example: Barcelona state: type: string description: State name example: Catalonia email: type: string description: Email of the location example: local1234@google.es longitude: type: number description: Longitude (gps) of the location example: 40.68906 latitude: type: number description: Latitude (gps) of the location example: 74.044636 status: type: string description: |- Status of the location, must be one of them: active inactive Default: active example: active score_exchange_id: type: integer format: int64 description: ID of the score exchange example: 12 schedule: type: string description: Schedule details example: 8:00 - 20:00 custom1: type: string description: Custom value example: custom value 1 custom2: type: string description: Custom value example: custom value 2 custom3: type: string description: Custom value example: custom value 3 custom4: type: string description: Custom value example: custom value 4 custom5: type: string description: Custom value example: custom value 5 custom6: type: string description: Custom value example: custom value 6 custom7: type: string description: Custom value example: custom value 7 custom8: type: string description: Custom value example: custom value 8 features: type: array items: $ref: '#/components/schemas/Feature' description: Array of features to which the location belongs to CreateaNewLocationresponse: title: CreateaNewLocationresponse required: - id - name - postal_code - address - address_extra - phone - country - currency - city - state - email - longitude - latitude - status - score_exchange_id - schedule - custom1 - custom2 - custom3 - custom4 - custom5 - custom6 - custom7 - custom8 - features type: object properties: id: type: integer format: int64 code: type: string name: type: string postal_code: type: string address: type: string address_extra: type: string phone: type: string country: type: string currency: type: string city: type: string state: type: string email: type: string longitude: type: number latitude: type: number status: type: string score_exchange_id: type: integer format: int64 schedule: type: string custom1: type: string custom2: type: string custom3: type: string custom4: type: string custom5: type: string custom6: type: string custom7: type: string custom8: type: string features: type: array items: $ref: '#/components/schemas/Feature1' description: '' example: id: 1234 code: 53345345B name: Local location postal_code: '08080' address: Joan Tshu address_extra: N1 phone: '638849999' country: ES currency: EUR city: Madrid state: Madrid email: local1234@test.test longitude: 41.62366 latitude: 71.0262336 status: active score_exchange_id: 15 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: test1 - id: 2 taxonomy_slug: test2 FeatureLocation: title: LocationFeatures type: object properties: id: type: integer format: int64 description: The external ID of the feature taxonomy_slug: type: string description: The slug of the taxonomy example: id: 1 taxonomy_slug: test1 Getlocationresponse: title: Getlocationresponse type: object properties: id: type: integer format: int64 description: ID of the location code: type: string name: type: string postal_code: type: string address: type: string address_extra: type: string phone: type: string country: type: string currency: type: string city: type: string state: type: string email: type: string longitude: type: number latitude: type: number status: type: string score_exchange_id: type: integer format: int64 schedule: type: string custom1: type: string custom2: type: string custom3: type: string custom4: type: string custom5: type: string custom6: type: string custom7: type: string custom8: type: string features: type: array items: $ref: '#/components/schemas/FeatureLocation' description: List of features example: id: 1234 code: 53345345B name: Local location postal_code: '08080' address: Joan Tshu address_extra: N1 phone: '638849999' country: ES currency: EUR city: Madrid state: Madrid email: local1234@test.test longitude: 41.62366 latitude: 71.0262336 status: active score_exchange_id: 15 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: test1 - id: 2 taxonomy_slug: test2 DeleteaLocationresponse: title: DeleteaLocationresponse required: - status type: object properties: status: type: string example: status: success UpdateaLocationrequest: title: UpdateaLocationrequest type: object properties: name: type: string description: Name example: Local number 1234 postal_code: type: string description: Postal code example: '08110' address: type: string description: Address of the location example: Joan Miró address_extra: type: string description: Extra information about the address. example: '31' phone: type: string description: Phone example: '678513344' country: type: string description: >- Code of the location's country according to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)(It must be Capitals letters) example: ES currency: type: string description: >- Code of the location's currency according to the [ISO 4217](https://en.wikipedia.org/wiki/List_of_circulating_currencies)(It must be Capitals letters) example: EUR city: type: string description: City name example: Barcelona state: type: string description: State name example: Catalonia email: type: string description: Email of the location example: local1234@google.es longitude: type: number description: Longitude (gps) of the location example: 40.68906 latitude: type: number description: Latitude (gps) of the location example: 74.044636 status: type: string description: |- Status of the location, must be one of them: active inactive Default: active example: active score_exchange_id: type: integer format: int64 description: ID of the score exchange example: 12 schedule: type: string description: Schedule details example: 8:00 - 20:00 custom1: type: string description: Custom value example: custom value 1 custom2: type: string description: Custom value example: custom value 2 custom3: type: string description: Custom value example: custom value 3 custom4: type: string description: Custom value example: custom value 4 custom5: type: string description: Custom value example: custom value 5 custom6: type: string description: Custom value example: custom value 6 custom7: type: string description: Custom value example: custom value 7 custom8: type: string description: Custom value example: custom value 8 features: type: array items: $ref: '#/components/schemas/Feature' description: Array of features to which the location belongs to UpdateaLocationresponse: title: UpdateaLocationresponse required: - id - name - postal_code - address - address_extra - phone - country - currency - city - state - email - longitude - latitude - status - score_exchange_id - schedule - custom1 - custom2 - custom3 - custom4 - custom5 - custom6 - custom7 - custom8 - features type: object properties: id: type: integer format: int64 code: type: string name: type: string postal_code: type: string address: type: string address_extra: type: string phone: type: string country: type: string currency: type: string city: type: string state: type: string email: type: string longitude: type: number latitude: type: number status: type: string score_exchange_id: type: integer format: int64 schedule: type: string custom1: type: string custom2: type: string custom3: type: string custom4: type: string custom5: type: string custom6: type: string custom7: type: string custom8: type: string features: type: array items: $ref: '#/components/schemas/Feature1' description: '' example: id: 1234 code: 53345345B name: Local location postal_code: '08080' address: Joan Tshu address_extra: N1 phone: '638849999' country: ES currency: EUR city: Madrid state: Madrid email: local1234@test.test longitude: 41.62366 latitude: 71.0262336 status: active score_exchange_id: 15 schedule: 8:00 - 20:00 custom1: custom value 1 custom2: custom value 2 custom3: custom value 3 custom4: custom value 4 custom5: custom value 5 custom6: custom value 6 custom7: custom value 7 custom8: custom value 8 features: - id: 1 taxonomy_slug: test1 - id: 2 taxonomy_slug: test2 CreateaNewLocationTaxonomyrequest: title: CreateaNewLocationTaxonomyrequest required: - name - slug type: object properties: name: type: string description: Name of the taxonomy example: Meat slug: type: string description: >- Slug of the taxonomy. The slug should be a short label for something, containing only letters, numbers, underscores or separators. example: meat_pub|1 CreateaNewLocationTaxonomyresponse: title: CreateaNewLocationTaxonomyresponse required: - id - name - slug - origin type: object properties: id: type: integer format: int64 name: type: string slug: type: string origin: type: string example: id: 1 name: Meat slug: meat_pub|1 origin: external DeleteaLocationTaxonomyresponse: title: DeleteaLocationTaxonomyresponse required: - status type: object properties: status: type: string example: status: success UpdateaLocationTaxonomyrequest: title: UpdateaLocationTaxonomyrequest required: - name type: object properties: name: type: string description: Name of the taxonomy example: Most visited UpdateaLocationTaxonomyresponse: title: UpdateaLocationTaxonomyresponse required: - status type: object properties: status: type: string example: status: success CreateaLocationFeaturerequest: title: CreateaLocationFeaturerequest required: - id - name type: object properties: id: type: integer format: int64 description: Unique identifier of the feature within its taxonomy. example: 1 name: type: string description: Name of the feature example: Barcelona CreateaLocationFeatureresponse: title: CreateaLocationFeatureresponse required: - external_id - id - name - slug - taxonomy_slug type: object properties: external_id: type: integer format: int64 id: type: integer format: int64 name: type: string slug: type: string taxonomy_slug: type: string example: external_id: 1 id: 1323542 name: Barcelona slug: region|1 taxonomy_slug: region DeleteaLocationFeatureresponse: title: DeleteaLocationFeatureresponse required: - status type: object properties: status: type: string example: status: success UpdateaLocationFeaturerequest: title: UpdateaLocationFeaturerequest required: - name type: object properties: name: type: string description: New name of the feature example: BCN UpdateaLocationFeatureresponse: title: UpdateaLocationFeatureresponse required: - external_id - id - name - slug - taxonomy_slug type: object properties: external_id: type: integer format: int64 id: type: integer format: int64 name: type: string slug: type: string taxonomy_slug: type: string example: external_id: 1 id: 1323542 name: BCN slug: region|1 taxonomy_slug: region CreateaNewPromotionrequest: title: CreateaNewPromotionrequest required: - id - name type: object properties: id: type: integer format: int64 description: ID of the promotion in form of an integer example: 1234 name: type: string description: Name example: Promotion 2x1 description: type: string description: Description example: Pay one and get the second one for free available_from: type: string description: Available from Date. example: '2016-01-01' available_to: type: string description: Available to Date. example: '2016-02-01' active: type: boolean description: |- An optional attribute to set the status of the promotion Default: true example: true discount: type: number description: >- Discount percentage (0 to 1) applied to the promotioned product. Default value: 0. example: 0.33 discount_type: type: string description: >- Type of discount applied to the promotioned product. Default value: 'percent'. Possible values: 'percent', 'cash'. affectation: type: string description: >- Affectation of the promotion. Possible values: 'activity', 'attribute', 'product' example: product min_units: type: integer format: int64 description: >- Minimum number of units that the customer must buy to apply the promotion. Default value: 1. example: 2 max_units: type: integer format: int64 description: >- Maximum number of units that the customer can buy to apply the promotion. Default value: 1. example: 2 min_money: type: number format: float description: >- Minimum amount of money that the customer must spend to apply the promotion. Default value: 0.5 max_money: type: number format: float description: >- Maximum amount of money that the customer can spend to apply the promotion. Default value: 10.5 cumulative: type: boolean description: >- An optional attribute to set if the promotion is cumulative with other promotions. Default value: false example: true feature_pks: type: string marketing_cost: type: number description: Total amount of money invested in advertising the promotion. example: 35975.52 created_at: type: string description: DateTime of the creation of the promotion. example: '2016-01-01T12:00:00Z' location_ids: type: array items: type: integer format: int64 description: >- Array of location ids that the promotion belongs to. Specify this param only if the promotions belongs to a group of locations, if the promotion is available in all locations you can ommit this param. feature_location_ids: type: array items: type: integer format: int64 description: >- Array of location category ids that the promotion applies to. Specify this param only if the promotion apply to a group of location categories, if the promotion applies to all locations you can ommit this param. product_ids: type: array items: type: integer format: int64 description: >- Array of product ids on which the promotion is applied. Specify this param only if the promotions belongs to a group of products. collective_ids: type: array items: type: integer format: int64 description: >- Array of collective id that the promotion applies to. Specify this param only if the promotion apply to a group of collectives, if the promotion applies to all customers you can ommit this param. This attribute is recomended for Colletive asignation. collective_slugs: type: array items: type: string description: >- Array of collective slugs that the promotion applies to. Specify this param only if the promotion apply to a group of collectives, if the promotion applies to all customers you can ommit this param.Only use this attribute if no ids available in your system. promotional_discount_name: type: string description: Name of the promotional type which the promotion is included. example: 2x1 DeleteaPromotionresponse: title: DeleteaPromotionresponse required: - status type: object properties: status: type: string example: status: success UpdateaPromotionrequest: title: UpdateaPromotionrequest type: object properties: name: type: string description: Name example: Promotion 2x1 description: type: string description: Description example: Pay one and get the second one for free available_from: type: string description: Available date. example: '2016-01-01' available_to: type: string description: Available date. example: '2016-02-01' active: type: boolean description: |- An optional attribute to set the status of the promotion Default: true example: true discount: type: number description: Discount percentage (0 to 1) applied to the promotioned product. example: 0.33 discount_type: type: string description: >- Type of discount applied to the promotioned product. Default value: 'percent'. Possible values: 'percent', 'cash'. affectation: type: string description: >- Affectation of the promotion. Possible values: 'activity', 'attribute', 'product' example: product min_units: type: integer format: int64 description: >- Minimum number of units that the customer must buy to apply the promotion. Default value: 1. example: 2 max_units: type: integer format: int64 description: >- Maximum number of units that the customer can buy to apply the promotion. Default value: 1. example: 2 min_money: type: number format: float description: >- Minimum amount of money that the customer must spend to apply the promotion. Default value: 0.5 max_money: type: number format: float description: >- Maximum amount of money that the customer can spend to apply the promotion. Default value: 10.5 cumulative: type: boolean description: >- An optional attribute to set if the promotion is cumulative with other promotions. Default value: false example: true feature_pks: type: string marketing_cost: type: number description: Total amount of money invested in advertising the promotion. example: 35975.52 created_at: type: string description: Date of the creation of the promotion. example: '2016-01-01T12:00:00Z' updated_at: type: string description: Date of the update of the promotion. example: '2016-01-01T12:00:00Z' location_ids: type: array items: type: integer format: int64 description: >- The complete list of location ids that this promotion belongs to. Important notice: sending this property will overwrite all previous locations with the new array you provide. If you send an empty list, it will delete all locations. feature_location_ids: type: array items: type: integer format: int64 description: >- Array of location category ids that the promotion applies to. Specify this param only if the promotion apply to a group of location categories, if the promotion applies to all locations you can ommit this param. product_ids: type: array items: type: integer format: int64 description: >- Array of product ids on which the promotion is applied. Important notice: sending this property will overwrite all previous products with the new array you provide. If you send an empty list, it will delete all products. collective_ids: type: array items: type: string description: >- Array of collective id that the promotion applies to. Specify this param only if the promotion apply to a group of collectives, if the promotion applies to all customers you can ommit this param. This attribute is recomended for Colletive asignation. collective_slugs: type: array items: type: string description: >- Array of collective slugs that the promotion applies to. Specify this param only if the promotion apply to a group of collectives, if the promotion applies to all customers you can ommit this param. Only use this attribute if no ids available in your system. promotional_discount_name: type: string description: Name of the promotional type which the promotion is included. example: 2x1 CheckAPIavailabilityresponse: title: CheckAPIavailabilityresponse required: - status type: object properties: status: type: string example: status: ok Discounts: title: Discounts required: - score - voucher - promotion type: object properties: score: type: integer format: int64 voucher: type: integer format: int64 promotion: type: integer format: int64 example: score: 0 voucher: 0 promotion: 0 Datum: title: Datum required: - month - year - discounts type: object properties: month: type: integer format: int64 year: type: integer format: int64 discounts: $ref: '#/components/schemas/Discounts' example: month: 1 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 Getadiscountreportresponse: title: Getadiscountreportresponse required: - data type: object properties: data: type: array items: $ref: '#/components/schemas/Datum' description: '' example: data: - month: 1 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 2 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 3 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 4 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 5 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 6 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 7 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 8 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 9 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 10 year: 2019 discounts: score: 0 voucher: 0 promotion: 0 - month: 11 year: 2019 discounts: score: 2 voucher: 3 promotion: 4 - month: 12 year: 2019 discounts: score: 5 voucher: 2 promotion: 7 Getadiscountreportresponse1: title: Getadiscountreportresponse1 required: - code - error type: object properties: code: type: string error: type: string example: code: invalid_request error: error message Printsalistofmessagesrequest: title: Printsalistofmessagesrequest required: - customer_id - size type: object properties: customer_id: type: integer format: int64 description: ID of the customer example: 345 size: type: integer format: int64 description: |- Number of messages minimum: 1 maximum: 10 example: 3 location_id: type: integer format: int64 description: >- ID of the location in form of an integer. It will print only messages from that location or without location example: 1 activity_id: type: integer format: int64 description: ID of the activity where the print happens example: 100005677 category: type: string description: Category of the voucher example: Summer exclude_ids: type: array items: type: integer format: int64 description: 'List of voucher ids to exclude before print ' debug: type: boolean description: |- If it is true the messages are not set as status = printed Default: `false` example: false available_redemptions: type: integer format: int64 description: Available redemptions example: 1 Printsalistofmessagesresponse: title: Printsalistofmessagesresponse type: object properties: code: type: string available_from: type: string available_to: type: string name: type: string description: type: string available_redemptions: type: integer format: int64 example: code: '123123123987987987' available_from: '2016-02-10' available_to: '2016-02-28' name: Discount meat 50% description: Discount meat 50% extended description available_redemptions: 1 x-tagGroups: - name: Customers tags: - customers - tiers, attributes & audiences - associations & merges - name: Customer Events tags: - carts - custom events - triggers - name: Loyalty & Gamification Campaigns tags: - discounts - Games - points & wallet - rewards - challenges - campaign coupons - campaign vouchers - name: Promotions Calculation tags: - simulate a cart - create a cart - create a custom event - process a trigger for a specific customer - name: Company Data tags: - products - product taxonomies - product features - locations - location taxonomies - location features - promotions - name: Others tags: - check