swagger: '2.0' info: title: Receipts API description: | API for managing receipts ## Changelog All notable changes to the API. ## 2024-04-01 > **update**: Remove enum requirement for `receipt.enrolled_by.type` and > add support for more `receipt.customer.type`. > See https://docs.dintero.com/customers-api.html#section/Changelog/2024-03-01 ## 2023-07-01 > **new** add support for `items.[].bonus_lines`, discounts with `bonus` refs and `total_bonus` > - [POST /v1/accounts/{aid}/receipts](#tag/receipts/operation/aid_receipts_post) ## 2020-05-01 > Fix the documentation for the response from listing customer receipts. The > receipts response was missing receipt items. > - [GET /receipts/customers/{customer_id}](#operation/aid_receipts_customers_cid_get) ## 2019-12-31 > Add support for `token_expire_days` parameter when creating > receipt. The token added to the receipt can be used to retrieve and claim > it. > - [POST /receipts](#operation/aid_receipts_post) > - [GET /receipts/receipt-token](#operation/aid_receipts_receipt_token_get) > - [POST /receipts/receipt-token](#operation/aid_receipts_receipt_token_post) ## 2019-11-31 > Improve documentation for receipt `receipt_id` property, > a non-empty value is required when creating receipts. > - [POST /receipts](#operation/aid_receipts_post) ## 2019-07-31 > Extend the receipt format with `store.mcc` property, > a four-digit merchant category code for classifying the merchant > - [POST /receipts](#operation/aid_receipts_post) > - ISO 18245 https://www.iso.org/standard/33365.html ## 2019-06-31 > The scope required for accessing endpoint has changed, > we will continue to support the old scopes but they was removed from > the documentation ## 2018-11-26 > Extend the `receipt.store` object with `business_name`, > an optional property for the store legal name. ## 2018-06-04 > Moved endpoint for search for receipt by receipt_id query parameter > - [GET /receipts/search](#operation/aid_receipts_rid_get) > Add support for updating anonymous receipt with > customer_id and discounts. > - [PUT /receipts/all/{receipt_id}](#operation/aid_receipts_update_put) ## 2018-04-11 > Rename property `store.created_on_terminal_id` to > `store.terminal_id`. > Extend `receipt.discount.refs`. Add `statistics` object > and stamp property to refs. The statistics object includes total amount, > usage, stamp and current debit_balance. > Correct type of `receipt.discount.refs.items.amount` to integer > (was string). ## 2018-02-02 > Extend receipt.discounts.refs. > Include amount and how the amount was applied to the receipt.items in > discount.refs > - [POST /discounts/available_for_receipt](#operation/aid_discounts_available_for_receipt_post) ## 2017-12-04 > Add `refs` to receipt discounts. The value > is used to record the reference between the owner of the > discount and how many times the discount was used on the > purchase. > Add monetary string properties suffixed with `_dwh`. > The new values can be used to store monetary value with > a resolution higher than the smallest unit for the > currency. > Define required properties for a receipt. > - *receipt.store.id* *receipt.receipt_id* *receipt.purchase_at* > Move `customer_id` from receipt customer to > receipt. ## 2017-11-22 > Move receipt `customer_*` properties into a > customer object. > - *customer_id* => *customer.customer_id* > - *customer_token_id* => *customer.token.token_id* > - *customer_token* => *customer.token.value* > - *customer_token_type* => *customer.token.value* > - *customer_pays_tax* => *customer.pays_tax* > Add support for more customer properties > in the receipt, (first_name, last_name, email, > phone_number, metadata, address and status). > Add support for adding delivery details to > the receipt. `receipt.delivery`. ## 2017-10-29 > Add line_id property to Receipt infocode_items (InfoCodeItem). ## 2017-10-27 > Change `dimension_lines` property to `dimension` > for Receipt items (ReceiptItem). > Fix typo, rename *card_amound* property to > `card_amount` for Payment card_info (CardInfo). contact: name: API Integration Support email: integration@dintero.com version: LATEST license: name: UNLICENSED url: https://dintero.com basePath: /v1 consumes: - application/json produces: - application/json security: - JWT: [] paths: /accounts/{aid}/receipts: post: operationId: aid_receipts_post summary: Create new Receipts description: | Post receipts scopes: - admin:receipts - write:receipts tags: - receipts x-scopes: - admin:receipts - write:receipts parameters: - $ref: '#/parameters/accountId' - name: token_expire_days in: query type: integer minimum: 1 description: | Generate tokens for the receipts created, the token can be used to retrieve the receipt from: - [GET /receipts](#operation/aid_receipts_receipt_token_get) Following values will be added to `extra_info` when receipt is created with this query parameter: - `dintero.receipt.token.value`: JWT token that can be used to retrieve the receipt. - `dintero.receipt.token.expires_at`: The date-time when the token expires. - `dintero.receipt.token.url`: URL to retrieve the receipt using the token. - name: data description: receipt in: body required: true schema: type: array items: allOf: - $ref: '#/definitions/Receipt' - properties: receipt_id: type: string minLength: 1 security: - JWT: [] responses: '200': description: Receipt created schema: type: object properties: receipts: type: array items: $ref: '#/definitions/Entity' duplicates: type: integer '400': $ref: '#/responses/BadRequest' '401': $ref: '#/responses/AccessForbidden' '404': $ref: '#/responses/Forbidden' '500': $ref: '#/responses/ServerError' /accounts/{aid}/receipts/all/{receipt_id}: put: operationId: aid_receipts_update_put summary: Update receipt description: | Update existing anonymous receipt. ### Limitation - update of customer_id is only allowed if the current customer_id is null. - update of discounts is only allowed if current discounts value is null or empty scopes: - admin:receipts - read:receipts x-scopes: - admin:receipts - read:receipts parameters: - $ref: '#/parameters/accountId' - $ref: '#/parameters/receipt_id' - name: data description: changes in: body required: true schema: type: object required: - customer_id properties: customer_id: type: string description: | Add customer_id to existing receipt. The customer id identifying the customer. (must not have trailing or leading spaces) example: C13db4f63 maxLength: 255 discounts: description: | Add discount to existing receipt. type: array items: $ref: '#/definitions/DiscountRefs' tags: - receipts security: - JWT: [] responses: '200': description: Receipt detail schema: $ref: '#/definitions/Receipt' '400': $ref: '#/responses/BadRequest' '401': $ref: '#/responses/AccessForbidden' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '500': $ref: '#/responses/ServerError' /accounts/{aid}/receipts/customer_segment: post: operationId: aid_receipts_customer_segment_post summary: Customer segmentation description: | Segment customer by receipt data scopes: - admin:receipts - read:receipts tags: - segment x-scopes: - admin:receipts - read:receipts parameters: - $ref: '#/parameters/accountId' - name: data description: segmentation on receipt data in: body required: true schema: type: object properties: purchase_from: type: string format: date-time purchase_to: type: string format: date-time store_ids: type: array items: type: string items: type: array items: type: object properties: id: type: string group: type: string security: - JWT: [] responses: '200': description: Customer matching segmentation schema: type: object properties: customers: type: array items: type: object properties: customer_id: type: string format: uuid purchases: type: integer example: 5 '400': $ref: '#/responses/BadRequest' '401': $ref: '#/responses/AccessForbidden' '403': $ref: '#/responses/Forbidden' '500': $ref: '#/responses/ServerError' /accounts/{aid}/receipts/customers/{customer_id}: get: operationId: aid_receipts_customers_cid_get summary: Customer Receipts collection description: | Get the receipts for a customer scopes: - admin:receipts - read:receipts - user:receipts tags: - customer receipts x-scopes: - admin:receipts - read:receipts - user:receipts parameters: - $ref: '#/parameters/accountId' - $ref: '#/parameters/customerId' - $ref: '#/parameters/limit' - $ref: '#/parameters/startingAfter' security: - JWT: [] responses: '200': description: Receipt collection schema: type: object properties: receipts: type: array items: $ref: '#/definitions/ReceiptMinimal' starting_after: type: string '401': $ref: '#/responses/AccessForbidden' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '500': $ref: '#/responses/ServerError' /accounts/{aid}/receipts/customers/{customer_id}/{receipt_id}: get: operationId: aid_receipts_customers_cid_rid_get summary: Customer receipt details description: | Get a customer receipt scopes: - admin:receipts - read:receipts - user:receipts tags: - customer receipts x-scopes: - admin:receipts - read:receipts - user:receipts parameters: - $ref: '#/parameters/accountId' - $ref: '#/parameters/customerId' - $ref: '#/parameters/receipt_id' security: - JWT: [] responses: '200': description: Receipt detail schema: type: object allOf: - $ref: '#/definitions/Receipt' '400': $ref: '#/responses/BadRequest' '401': $ref: '#/responses/AccessForbidden' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '500': $ref: '#/responses/ServerError' /accounts/{aid}/receipts/customers/{customer_id}/{receipt_id}/change_customer_id: post: operationId: aid_receipts_customers_cid_rid_change_customer_id_post summary: Change customer_id description: | Update customer_id for an receipt, i.e. move the receipt to a new customer > **warning**: The receipt will no longer be accessible > by the previous customer_id Following extra_info field will be added to the receipt when customer_id is changed using key - `dintero.receipts.change_customer_id.{timestamp}.{hash}` The content of the extra_info will be a JSON string containing: - created_at - created_by - old - new scopes: - admin:receipts tags: - customer receipts x-scopes: - admin:receipts - read:receipts - user:receipts parameters: - $ref: '#/parameters/accountId' - $ref: '#/parameters/customerId' - $ref: '#/parameters/receipt_id' - name: data description: Receipt update in: body required: true schema: type: object properties: customer_id: type: string maxLength: 255 minLength: 1 description: | New customer_id (must not have trailing or leading spaces). security: - JWT: [] responses: '200': description: Receipt detail with new customer_id schema: type: object allOf: - $ref: '#/definitions/Receipt' '400': $ref: '#/responses/BadRequest' '401': $ref: '#/responses/AccessForbidden' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' '500': $ref: '#/responses/ServerError' /accounts/{aid}/receipts/receipt-token: post: operationId: aid_receipts_receipt_token_post summary: Claim receipt by token description: | Update `customer_id` on receipt identified by token. The token will be invalid after the claim. scopes: - admin:receipts - write:receipts - user:receipts tags: - receipts x-scopes: - admin:receipts - write:receipts - user:receipts - public:receipts parameters: - $ref: '#/parameters/accountId' - name: token description: JWT token for receipt in: query required: true type: string - name: data description: new customer id in: body required: true schema: type: object required: - customer_id properties: customer_id: type: string security: - JWT: [] responses: '200': description: Receipt claimed schema: $ref: '#/definitions/Receipt' '400': $ref: '#/responses/BadRequest' '401': $ref: '#/responses/AccessForbidden' '403': $ref: '#/responses/Forbidden' '500': $ref: '#/responses/ServerError' get: operationId: aid_receipts_receipt_token_get summary: Get receipt by token description: | Get receipt from token. The token must be a signed JWT token containing the `customer_id` and `receipt_id` to fetch. scopes: - admin:receipts - read:receipts - user:receipts - public:receipts parameters: - $ref: '#/parameters/accountId' - name: token description: JWT token for receipt in: query required: true type: string tags: - receipts x-scopes: - admin:receipts - read:receipts - user:receipts security: - JWT: [] responses: '200': description: Receipt schema: type: object $ref: '#/definitions/Receipt' '400': $ref: '#/responses/BadRequest' '401': $ref: '#/responses/AccessForbidden' '403': $ref: '#/responses/Forbidden' '500': $ref: '#/responses/ServerError' /accounts/{aid}/receipts/search: get: operationId: aid_receipts_rid_get summary: Receipt search description: | Get receipts matching receipt_id (POS id) scopes: - admin:receipts - read:receipts parameters: - $ref: '#/parameters/accountId' - $ref: '#/parameters/receiptId' tags: - receipts x-scopes: - admin:receipts - read:receipts security: - JWT: [] responses: '200': description: Receipt collection schema: type: object properties: receipts: type: array items: $ref: '#/definitions/Receipt' starting_after: type: string '401': $ref: '#/responses/AccessForbidden' '403': $ref: '#/responses/Forbidden' '500': $ref: '#/responses/ServerError' definitions: Entity: type: object properties: id: type: string format: uuid description: | An UUID that uniquely identifies the resource readOnly: true created_at: type: string format: date-time description: | The date-time when the resource was created readOnly: true created_by: type: string example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e description: | The ID of the user/client created the resource readOnly: true updated_at: type: string format: date-time description: | The date-time when the resource was last updated readOnly: true deleted_by: type: string example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e description: | The ID of the user/client created the resource readOnly: true deleted_at: type: string format: date-time readOnly: true Item: type: object properties: id: type: string example: b714118 group_id: type: string example: B1 Limitation: type: object properties: discount_activation: type: array description: | Dynamically control if the discount should be active. items: minItems: 1 maxItems: 1 type: object required: - type - value properties: type: type: string description: | - `deactivate_if_discount_active`: The discount is deactivated if the value match the `id` of another active discount available for the purchase enum: - deactivate_if_discount_active value: type: string description: | Value given the type discount_hours: type: object description: | Limit the discount to hours of the day required: - hours properties: timezone: description: | The timezone identifier for the hour start/end, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for examples. DST is handled when using a Timezone with DST. default: Europe/Oslo type: string hours: description: | an array of periods, day and time when discount will be available. Multiple periods for one day is accepted. Any hour of purchase is accepted if the array is empty. type: array items: type: object required: - day - start - end properties: day: type: string enum: - mon - tue - wed - thu - fri - sat - sun start: type: string format: ^([01]?[0-9]|2[0-3]):[0-5][0-9]$ example: '10:00' end: type: string format: ^([01]?[0-9]|2[0-3]):[0-5][0-9]$ example: '20:00' discount_reward_usage: type: integer description: | Limit the number of rewards to be given in a purchase where multiple receipt items match the requirement example: 1 default: -1 discount_combination: type: integer description: | Limit how many other discounts can be combined in a purchase where multiple discounts are applicable. default: -1 enum: - -1 - 0 discount_eligible: type: string description: | Limit what items in the purchase is eligible for this discount enum: - item_eligible_for_discount - item_eligible_for_discount_no_discount - receipt_no_discount default: item_eligible_for_discount discount_repeat_usage: type: integer description: | Limit how many purchases the discount can be used default: -1 stamp_expire_days: type: integer description: | Number of days between first and last (exceeding count) stamp where reward will be given example: 100 default: -1 blacklist: type: array description: | items not eligible for discount. items: $ref: '#/definitions/Item' minItems: 1 CustomerRequirement: type: object properties: addresses: type: array description: Require customer to have one or more addresses matching the properties. All properties defined must match a single address. items: type: object minItems: 1 maxItems: 5 properties: country: type: array example: - 'NO' items: type: string minItems: 1 maxItems: 5 postal_code: type: array example: - '0349' items: type: string minItems: 1 maxItems: 5 postal_place: type: array example: - Oslo items: type: string minItems: 1 maxItems: 5 custom_type: type: array example: - offsite items: type: string minItems: 1 maxItems: 5 type: type: array example: - custom items: type: string minItems: 1 maxItems: 5 company: type: object description: | Require customer to be a company matching all properties defined. properties: bussiness_name: type: array example: - TKP tech AS items: type: string minItems: 1 maxItems: 5 department: type: array example: - production - research items: type: string minItems: 1 maxItems: 5 industry: type: array example: - J62.0.1 - J62.0.2 items: type: string minItems: 1 maxItems: 5 number_of_employees: type: array example: - '20' items: type: string minItems: 1 maxItems: 5 organization_number: type: array example: - 123456789MVA items: type: string minItems: 1 maxItems: 5 website: type: array example: - https://dintero.com items: type: string minItems: 1 maxItems: 5 date_of_birth: type: array example: - '1990-09-20' - '1990-05-10' items: type: string minItems: 1 maxItems: 5 enrolled_by: type: object properties: type: type: array example: - url items: type: string minItems: 1 maxItems: 5 value: type: array example: - https://mypage.example.dintero.com items: type: string minItems: 1 maxItems: 5 favorite_store: type: array example: - sc029 items: type: string minItems: 1 maxItems: 5 first_name: type: array example: - John items: type: string minItems: 1 maxItems: 5 gender: type: array example: - male items: type: string minItems: 1 maxItems: 5 last_name: type: array example: - Doe items: type: string minItems: 1 maxItems: 5 marketing_consent: type: object properties: email: type: object properties: consent: type: array example: - 'true' items: type: string minItems: 1 maxItems: 5 sms: type: object properties: consent: type: array example: - 'true' items: type: string minItems: 1 maxItems: 5 status: type: array example: - vip description: | limit discount to only receipt where customer status is included in the receipt and match one of the status values required by the discount items: type: string minItems: 1 maxItems: 5 term: type: object properties: id: type: array items: type: string minItems: 1 maxItems: 5 type: type: array items: type: string minItems: 1 maxItems: 5 attributes: type: object description: | Limit discount to only receipt where customer attributes are included and match one of the values required by the discount additionalProperties: type: array items: type: string minItems: 1 maxItems: 5 ItemMixProperty: type: object description: | Use mix in case where all items are required in one purchase. A reward will be eligible to all items in the mix that has `mix.reward_eligible=true` required: - quantity - reward_eligible properties: items: description: | Acceptable items for the mix "item" (`any`). No wildcard `*` is accepted. type: array example: - id: b714118 - group_id: g4 items: type: object minItems: 1 properties: id: type: string example: b714118 format: ^(\*.+|(?!\*).*)$ group_id: type: string format: ^(\*.+|(?!\*).*)$ example: g4 quantity: type: number description: | minimum quantity of given item (match by id or group) by the mix minimum: 0 reward_eligible: type: boolean description: | The item will be eligible for discount when calculating the reward Example: The value of `discount_item_new_price` reward will be the total price of all items in a mix that has the applicable set to `true` StoreRequirement: type: object properties: id: type: array items: type: string example: sc029 name: type: array description: | name of the store, aka trade name of the store items: type: string example: SC Oslo business_name: type: array description: | Official name of the person or entity that owns the store. items: type: string example: SC Oslo AS address: type: object description: Require customer to have one or more addresses matching the properties. All properties defined must match a single address. properties: country: type: array example: - 'NO' items: type: string minItems: 1 maxItems: 5 postal_code: type: array example: - '0349' items: type: string minItems: 1 maxItems: 5 postal_place: type: array example: - Oslo items: type: string minItems: 1 maxItems: 5 chain: type: array items: type: string example: SuperChain email: type: array items: type: string example: contact@superchain.com gln: type: array items: type: string example: '5790001398644' organization_number: type: array items: type: string example: 123456789MVA phone_number: type: array items: type: string example: '+4738260107' mcc: type: array description: | A four-digit Merchant Category Code (MCC) for the store [ISO 18245:2003](https://www.iso.org/standard/33365.html) items: type: string format: iso-18245 example: 5814 mcc_ranges: type: array description: | Ranges of MCC codes to accept the discount for. Multiple ranges are possible. Prefer `mcc` if not a range. items: type: object required: - start - end properties: start: type: string format: iso-18245 example: 5814 minimum: 4 maximum: 4 pattern: ^\d{4}$ end: type: string format: iso-18245 example: 5815 minimum: 4 maximum: 4 pattern: ^\d{4}$ bax: type: array description: | Merchant number associated with the stores payment terminal items: type: string example: '102603' terminal_id: type: array description: | Id to a specific point-of-sale (POS) terminal or workstation items: type: string example: T0292 BaseRequirement: type: object description: | Discount base requirement properties: customer: $ref: '#/definitions/CustomerRequirement' item: type: object properties: quantity: type: number description: | minimum number of items default: 0 minimum: 0 mixes: type: array minItems: 1 description: | Required mix items for the discount. A purchase must include `all` the items to fulfill the `item.mixes` requirement. items: $ref: '#/definitions/ItemMixProperty' items: type: array description: | Required items for the discount A purchase can include `any` of the items to fulfill the `item.items` requirement. The values contols if the reward is given on the receipt (all items) or if they are limited to matching items **Receipt** - A rule with no items or items with only wildcard items **Item** - A rule with one or more items (except wildcard) - A rule with a single item `{"id": "ANY_ITEM"}` in items items: $ref: '#/definitions/Item' minItems: 1 store_ids: type: array description: | `DEPRECATED`: [@since 2021-09-01](#section/Changelog/2021-09-01) items: type: string example: sc029 gross_amount: type: integer description: | Minimum gross amount on purchase. Monetary amount in smallest unit for the currency default: 0 currencies: description: | List of valid currencies, or `[{"anything-but": ["NOK"]}]` to exclude currencies. Currency format is the three-character [ISO-4217 currency](https://en.wikipedia.org/wiki/ISO_4217). type: array items: x-anyOf: - type: object properties: anything-but: type: array items: type: string example: NOK - type: string example: NOK stamp: type: integer description: | Stamp count required for the reward example: 5 discount_code: type: string description: | A code required for the reward. The purchase must include the promotion code in the `receipt.discount_code` property or as an `receipt.item` where the `item.id` is the promotion code. example: TACO store: $ref: '#/definitions/StoreRequirement' Requirement: type: object allOf: - $ref: '#/definitions/BaseRequirement' - required: - purchase_from - purchase_to properties: purchase_from: type: string format: date-time purchase_to: type: string format: date-time Reward: type: object required: - type - value properties: type: type: string description: | Reward Type: * `discount_amount` - value as discount * `discount_percent` - value percentage of gross amount as discount * `discount_item_new_price` - discount as old price subtracted with value * `discount_item_quantity` - number of items to get as discount (free) * `discount_item_percent` - percent discount of the cheapest item (stamp) as discount * `discount_debit` - value as discount, remaining amount after a purchase will be available in future purchases (if not limited by usage) * `discount_mix_new_price` - discount as old mix total value (reward_eligible=true) subtracted with value enum: - discount_amount - discount_percent - discount_item_new_price - discount_item_quantity - discount_item_percent - discount_mix_new_price - discount_debit value: type: - integer - number example: 10000 description: | The reward value, unit of the value is resolved from the reward type Examples: - Percent: 10.5 - Amount: 10000 (amount in smallest unit for the currency) - Quantity: 1 minimum: 1 values: description: | Reward values that is used to "override" the reward value for matching items. Add support for having a single rule for multiple items that gives different reward value for each items > Only available for rules where `requirements.item.items` is non-empty. type: array minItems: 1 items: type: object required: - items - value properties: items: type: array minItems: 1 description: | `id` or `group_id` is required, if both are included both id and group id must match items: type: object properties: id: type: string example: b714118 group_id: type: string example: B1 value: type: number base: type: string description: | Let the discount reward be calculated from net or gross price. Not applicable for `discount_item_new_price` *Example*: item A à 100,- NOK with existing rebate of 20,- - 10% net reward is 10% of 80,- : 8,- - 10% gross reward is 10% of 100,- : 10,- * *net*: `gross - "any existing discounts"` * *gross*: `"total expense amount, including taxes"` default: gross enum: - net - gross effect: type: string description: | How the reward will be added to the receipt. - `discount`: the reward will be applied as a discount directly on the receipt - `bonus`: the reward will be accumulated as bonus on the customers discount balance default: discount enum: - discount - bonus Links: description: Links to resources related to the discount type: array example: - href: https://example.dintero.com/c/photos/2018/6_20_thumbnail_discount_image.png rel: thumbnail_discount_image - href: https://example.dintero.com/c/photos/2018/6_20_medium_discount_image.png rel: medium_discount_image - href: https://example.dintero.com/shop?utm_source=dintero&utm_medium=email&utm_campaign=spring-summer rel: webshoop - href: https://example.dintero.com/newsletter/2018.pdf rel: newletter type: application/pdf items: type: object maxItems: 10 required: - href properties: href: description: The URL of the link. type: string format: uri rel: description: | Specifies the relationship between the discount and the link Following `rel` values are reserved for specific usage - thumbnail_discount_image: link to discount image - medium_discount_image: link to discount image - large_discount_image: link to discount image - webshop: link to site where the discount may be used type: string type: type: string description: Specifies the media type of the link Discount: required: - requirement - reward properties: id: type: string format: uuid description: | An UUID that uniquely identifies the resource readOnly: true created_at: type: string format: date-time description: | The date-time when the resource was created readOnly: true created_by: type: string example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e description: | The ID of the user/client created the resource readOnly: true updated_at: type: string format: date-time description: | The date-time when the resource was last updated readOnly: true deleted_by: type: string example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e description: | The ID of the user/client created the resource readOnly: true deleted_at: type: string format: date-time readOnly: true campaign_id: type: string description: | The campaign the rule belongs to active: description: | the discount is active and can be available for purchase (if given to any or all customers) type: boolean default: true private: description: | the discount will be excluded from public discount collection (GET /discounts/public/rules). type: boolean default: false updated_by: type: string example: 3d1e4824-5474-48e7-a369-4f603fa4c5b8 description: | The ID of the user/client that last updated the resource readOnly: true type: type: string description: The discount base type * `receipt` discount is given on receipt * `item` discount is given to items enum: - item - receipt readOnly: true name: type: string example: Spar 100,- receipt_text: type: string description: | Text that should be used when displaying the discount, e.g. on receipt example: Mai Salg visible_from: type: string format: date-time description: | Make the discount visible to the customer from given date. Default behavior is to only return discount to the customer where the current time is between purchase_from and purchase_to description: type: string example: Gjør et Stablestol kupp! limitation: $ref: '#/definitions/Limitation' requirement: $ref: '#/definitions/Requirement' reward: $ref: '#/definitions/Reward' metadata: type: object maxProperties: 10 description: | Additional metadata about the discount Metadata prefixed with `dintero:exclude:public:` will be excluded when listing the rules from the public endpoint - [GET /v1/accounts/{aid}/discounts/public/rules](#operation/aid_discounts_public_get) and included in all other endpoints that returns discount rules example: campaign_id: V101 is_featured: true dintero:private_text:kind: Gold links: $ref: '#/definitions/Links' DiscountRefs: allOf: - $ref: '#/definitions/Discount' - properties: refs: type: array description: | References to instances of the discount, a customer can have multiple instances of the same discount, this propery list the instances used items: type: object properties: id: type: string description: | reference id to the customer instance of the discount example: e3da6be5-d8e0-466c-af66-b7f69472ebb5 stamp: type: integer description: | number of stamp collected by the discount when used on the receipt. amount: type: integer description: | reward amount for the the ref used, monetary amount in smallest unit for the currency example: 10000 bonus: type: integer description: | reward bonus for the ref used example: 9050 statistics: type: object description: | statistics for given discount instance (ref) properties: amount: type: integer description: | total amount discount given, inclusive discount amounts from previous purchases where the the discount was used example: 15050 bonus: type: integer description: | total bonus given, inclusive bonus from previous purchases where the the discount was used example: 11050 debit_balance: type: integer description: | the discount debit balance, only applicable if discount reward type is `discount_debit` example: 12350 stamp: type: integer description: | total stamp collected by the discount, inclusive previous purchases example: 11 usage: type: integer description: | total times the discount reward was used, inclusive discount usage from previous purchases example: 2 items: type: array description: | Items receiving the discount, list what items received an discount_lines entry for this discount example: - line_id: 1 amount: 3000 - line_id: 5 amount: 7000 items: type: object properties: line_id: type: integer description: | item line_id bonus: type: integer description: bonus for given line_id amount: type: integer description: | discount amount for given line_id monetary amount in smallest unit for the currency usage: type: integer description: number of times the ref was used example: 1 Address: type: object required: - address_line - postal_place - country properties: address_line: type: string example: Sommerkroveien 34 address_line_2: type: string example: PB 123 postal_code: type: string example: '0349' postal_place: type: string example: Oslo country: type: string format: iso-3166-1 description: | ISO 3166-1 country code example: 'NO' Store: type: object required: - id properties: id: type: string example: sc029 name: type: string description: | name of the store, aka trade name of the store example: SC Oslo business_name: type: string description: | Official name of the person or entity that owns the store. example: SC Oslo AS address: $ref: '#/definitions/Address' chain: type: string example: SuperChain email: type: string example: contact@superchain.com gln: type: string example: '5790001398644' organization_number: type: string example: 123456789MVA phone_number: type: string example: '+4738260107' mcc: type: string format: iso-18245 description: | A four-digit Merchant Category Code (MCC) for the store [ISO 18245:2003](https://www.iso.org/standard/33365.html) example: '5814' minimum: 4 maximum: 4 bax: type: string example: '102603' description: | Merchant number associated with the stores payment terminal terminal_id: type: string description: | Id to a specific point-of-sale (POS) terminal or workstation example: T0292 InfoCodeItem: type: object properties: line_id: type: integer example: 1 amount: type: integer description: | Monetary amount in smallest unit for the currency amount_dwh: type: string example: '1.14' description: Monetary value with decimal infocode_id: type: string sub_infocode_id: type: string information: type: string input_type: type: integer withdrawal_from_stock: type: boolean example: false TaxItem: type: object properties: amount: type: integer example: 5584 description: | Monetary amount in smallest unit for the currency amount_dwh: type: string example: '5584.0440' description: Monetary value with decimal exempt: type: boolean example: false included_in_price: type: boolean example: true percentage: type: number example: 25 tax_basis: type: integer example: 27920 description: Total monetary value without tax tax_basis_dwh: type: string example: '27920.22' description: Total monetary value without tax in decimal tax_code: type: string example: '3' tax_group: type: string example: Vmva-høy Dimension: type: object description: | Identify item attributes, such as size and color properties: color: type: string size: type: string style: type: string config: type: string variant: type: string DiscountType: type: string enum: - customer - periodic - manual - loyalty - total - employee - external DiscountItem: type: object properties: amount: type: integer example: 4400 description: | Monetary amount in smallest unit for the currency percentage: type: number description: | Optional, set if the amount given was from a percentage discount example: 44 discount_type: $ref: '#/definitions/DiscountType' discount_id: type: string example: 766da0ef-9283-42bd-b012-0582344ec53c description: type: string line_id: type: integer example: 1 BonusItem: type: object properties: bonus: type: integer example: 3130 description: Bonus in smallest unit for the currency percentage: type: number description: | Optional, set if the bonus given was from a percentage discount example: 10 discount_type: $ref: '#/definitions/DiscountType' discount_id: type: string example: 766da0ef-9283-42bd-b012-0582344ec53c description: type: string line_id: type: integer example: 1 ExtraInfo: type: object properties: key: type: string value: type: string value_type: type: string enum: - string - integer - number - boolean - datetime ReceiptItem: type: object properties: id: type: string example: '175938' groups: type: array example: - id: B234 name: Stol - id: B1 name: Møbel items: type: object required: - id properties: id: type: string description: group id name: type: string description: group name quantity: type: number example: 2 default: 1 unit: type: string example: stk description: unit type description: type: string example: Stablestol for utendørsbruk description_alias: type: string example: Stablestol net_amount: type: integer example: 27840 description: | Monetary amount in smallest unit for the currency after discounts for items in this line net_amount_dwh: type: string example: '27840.10' description: | Monetary amount in smallest unit for the currency after discounts for items in this line in decimal gross_amount: type: integer example: 39800 description: | Monetary amount in smallest unit for the currency before discounts for items in this line gross_amount_dwh: type: string example: '34800.12' description: | Monetary amount in smallest unit for the currency before discounts for items in this line in decimal unit_gross_price: type: integer example: 10900 tax_percent: type: number example: 25 line_id: type: integer example: 1 barcode: type: string example: '3123212343212' cost_price: type: integer example: 2033 description: The purchase price the company pay for item voided: type: boolean example: false scale_item: type: boolean example: false description: | The price is calculated from scale (weight/volume). eligible_for_discount: type: boolean example: true included_in_total_discount: type: boolean example: true price_has_been_keyedIn: type: boolean example: false discount_has_been_keyedIn: type: boolean example: false is_return_item: type: boolean example: false is_linked_item: type: boolean example: false is_virtual_product: type: boolean example: false is_changed: description: Discount applied to gross amount type: boolean example: true salesperson_id: type: string description: | Id of the sales person if other then the operator example: '000111' salesperson_name: type: string description: | Name of the sales person example: Jesper serial_id: type: string example: '32424234231312312' comment: type: string example: Kan være hva som helst infocode_lines: type: array items: $ref: '#/definitions/InfoCodeItem' tax_lines: type: array items: $ref: '#/definitions/TaxItem' dimension: $ref: '#/definitions/Dimension' discount_lines: type: array items: $ref: '#/definitions/DiscountItem' bonus_lines: type: array items: $ref: '#/definitions/BonusItem' extra_info: type: array items: $ref: '#/definitions/ExtraInfo' CardInfo: type: object properties: balance_amount: type: integer description: | Monetary amount in smallest unit for the currency card_amount: type: integer description: | Monetary amount in smallest unit for the currency issuer_id: type: integer issuer_name: type: string example: Barcley session_id: type: string example: '022' terminal_id: type: string example: '71015233' card_number: type: string example: '************00198-1' card_type: type: string example: VISA receipt: type: string example: | BAX: 111010-71015233\n\r\11/11/2015 14:41\n\r\345849\n\r\ VISA CLASSIC\n\r\************5671\n\r\AID:A0000000031010\n\r\ REF:011 006687000000\n\r\RESP:00 GODKJENT\n\r\RETUR AV VARER\n\r \NOK= 50.00\n\r\SIGNATUR................\n\r \KORTHOLDERS KOPI PaymentItem: type: object properties: line_id: type: integer example: 1 amount: type: integer description: | Monetary amount in smallest unit for the currency type_id: type: string token_id: type: string description: Id of the token example: 983558fe-05bd-495f-92b5-9075d085db32 token_type: type: string description: The token issuer example: VIPPS description: type: string voided: type: boolean card_info: $ref: '#/definitions/CardInfo' reference_id: type: string example: B00668107235 infocode_lines: type: array items: $ref: '#/definitions/InfoCodeItem' Receipt: allOf: - $ref: '#/definitions/Entity' - required: - store - receipt_id - purchase_at properties: discounts: description: | List all discounts referenced in discount_lines type: array items: $ref: '#/definitions/DiscountRefs' store: $ref: '#/definitions/Store' items: type: array items: $ref: '#/definitions/ReceiptItem' receipt_id: type: string example: '714118' delivery: type: object description: | Details for the delivery properties: first_name: type: string example: John last_name: type: string example: Doe email: type: string example: customer@example.com phone_number: type: string description: | A phone number in E.164 number formatting. format: ^\+?[1-9]\d{1,14}$ example: '+4799999999' address: $ref: '#/definitions/Address' customer_id: type: string description: | The customer id identifying the customer. (must not have trailing or leading spaces) example: C13db4f63 maxLength: 255 customer: type: object description: | The customer, owner of the receipt properties: gender: type: string example: male first_name: type: string example: John last_name: type: string example: Doe email: type: string example: customer@example.com metadata: type: object description: | A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format. example: dob_year: 1985 phone_number: type: string description: | A phone number in E.164 number formatting. format: ^\+?[1-9]\d{1,14}$ example: '+4799999999' addresses: type: array items: allOf: - $ref: '#/definitions/Address' - properties: type: type: string custom_type: type: string pays_tax: type: boolean description: | Is customer required to pay tax example: false date_of_birth: type: string format: date x-nullable: true example: '1990-09-20' enrolled_by: type: object required: - value description: discribe where customers was recruit from properties: type: type: string description: | Enrollment type, e.g. `url`, `store`, `qr_code`, any string example: url value: type: string x-nullable: true example: https://facebook.com favorite_store: type: string x-nullable: true description: customer favorite store company: type: object required: - bussiness_name description: | Company details, supported when type is Company properties: organization_number: type: string description: Companys identification number example: 123456789MVA bussiness_name: type: string example: TKP tech AS department: type: string description: companys department example: sales department industry: type: string example: computer industry website: type: string number_of_employees: type: string marketing_consent: type: object description: Customers consent for marketing in different channels properties: sms: type: object properties: consent: type: boolean example: true updated_at: readOnly: true type: string format: date-time example: '2018-01-12T13:42:00Z' description: | The date-time when the resource was last updated: email: type: object properties: consent: type: boolean example: true updated_at: readOnly: true type: string format: date-time example: '2018-01-12T13:42:00Z' description: | The date-time when the resource was last updated: status: type: string description: | Status of the customer term: description: The term and condition accepted by the customer properties: id: type: string type: type: string enum: - customer - company - contact - employee - other description: | Describe type of an customer. Company only allowed to be set when the type is "Company" token: type: object description: | Token used to identify the customer properties: token_id: type: string description: | Id of token identifying the customer example: 983558fe-05bd-495f-92b5-9075d085db32 value: type: string description: | Token value that combined with type was used to identify the customer example: 5345346544ffea22 type: type: string description: The token issuer example: VIPPS gross_amount: type: integer description: | Monetary amount in smallest unit for the currency before discounts example: 59800 gross_amount_dwh: type: string description: | Monetary amount in smallest unit for the currency before discounts with decimal example: '59800.01' net_amount: type: integer example: 47840 description: | Monetary amount in smallest unit for the currency after discounts net_amount_dwh: type: string description: Monetary value in smallest unit for the currency after discounts with decimal example: '47840.01' round_off_to_coin: type: integer example: 100 currency: type: string example: NOK description: | The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217 purchase_at: description: | The date and time for the receipt purchase type: string format: date-time order_number: type: string example: order12345 transaction_date: type: string format: date-time amount_due: type: integer description: | How much more need to be paid before the transaction is completed. Monetary amount in smallest unit for the currency example: 2050 amount_due_dwh: type: string example: '2050.10' description: Monetary value with decimal no_of_items: type: number description: | How many items did the customer buy example: 4 is_changed: description: Discount applied to gross amount type: boolean transaction_id: type: string example: SC999-9991-1828 total_discount: type: integer example: 0 total_manual_discount_amount: type: integer example: 0 description: | Monetary amount in smallest unit for the currency total_manual_percentage_discount: type: integer example: 0 operator_id: type: string description: POS user example: '000210' operator_name: type: string description: Name of the POS user example: Ole Anders salesperson_id: type: string description: ID of the POS user example: '000111' salesperson_name: type: string example: Jesper entry_status: type: string description: Status for the transaction enum: - None - Voided - Posted - Concluded - Cancelled - OnHold - Training comment: type: string example: Kunden ønsker mer for info tax_lines: description: | Breakdown of the tax to different tax groups type: array items: $ref: '#/definitions/TaxItem' payments: type: array items: $ref: '#/definitions/PaymentItem' infocode_items: type: array items: $ref: '#/definitions/InfoCodeItem' receipt_text: type: string discount_code: type: array items: type: string extra_info: type: array items: $ref: '#/definitions/ExtraInfo' Error: type: object required: - error properties: error: type: object required: - message properties: code: type: string description: The code used to identify the error/warning errors: type: array description: The nested error(s) encountered during validation items: type: object message: type: string description: The human readable description of the error/warning ReceiptMinimal: allOf: - $ref: '#/definitions/Entity' - properties: store: $ref: '#/definitions/Store' items: type: array items: $ref: '#/definitions/ReceiptItem' gross_amount: type: integer example: 47840 description: | Monetary amount in smallest unit for the currency net_amount: type: integer example: 38000 description: | Monetary amount in smallest unit for the currency after discounts currency: type: string example: NOK description: | The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217 purchase_at: type: string format: date-time parameters: accountId: name: aid description: | An id that uniquely identifies the account. in: path required: true type: string format: ^[PT]{1}\d{8}$ minLength: 9 maxLength: 9 receipt_id: name: receipt_id description: | A string that uniquely identifies POS receipt in: path required: true type: string customerId: name: customer_id description: | The customer id you have defined for the customer. (must not have trailing or leading spaces) in: path required: true type: string maxLength: 255 limit: name: limit in: query description: | A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items. type: integer minimum: 1 maximum: 100 default: 10 startingAfter: name: starting_after in: query description: | cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, end the result contains `paging_token=pt1`, your subsequent call can include `starting_after=pt1` in order to fetch the next page of the list. type: string required: false receiptId: name: receipt_id description: | A string that uniquely identifies POS receipt in: query required: true type: string responses: BadRequest: description: Bad / Invalid request schema: $ref: '#/definitions/Error' AccessForbidden: description: Access forbidden, invalid JWT token was used schema: $ref: '#/definitions/Error' Forbidden: description: Forbidden schema: $ref: '#/definitions/Error' ServerError: description: Unexpected Error schema: $ref: '#/definitions/Error' NotFound: description: Resource was not found schema: $ref: '#/definitions/Error' securityDefinitions: JWT: type: apiKey name: Authorization description: | Bearer authentication (also called token authentication) should be used when accessing the API. Use [Get Token](https://docs.dintero.com/api.html#operation/aid_auths_oauth_token_post) to get an access token for client credentials Authorization by using the **Bearer** schema The content of the header should look like the following: Authorization: Bearer {access_token} where the **access_token** is JSON Web Tokens (JWT). in: header x-example: Bearer x-servers: - url: https://api.dintero.com/v1 x-tagGroups: - name: receipts tags: - receipts - customer receipts - segment