logo
API docs by Redocly

Dintero API (LATEST)

Download OpenAPI specification:Download

API Integration Support: integration@dintero.com License: UNLICENSED

API for managing Receipts, Discounts, Customers, Wallets and Webhooks

Introduction

The Dintero API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode incur no cost.

Downloads

Download the OpenAPI specification

  • customers : API for managing customers

  • discounts : API for managing discount for customers

  • products : API for managing products

  • hooks : API for managing webhooks

  • receipts : API for managing receipts

  • wallets : API for managing virtuall cards, digital gift cards and transactions

authenticate

Authorize Passwordless link

This endpoint is used to authorize Passwordless link sent to user by email/sms.

A valid request will redirect to This is the OAuth 2.0 grant that Client-side web apps utilize in order to access an API.

Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

query Parameters
audience
required
string

The unique identifier of the target API you want to access.

response_type
required
string
Value: "authenticate"

This will specify the type of token you will receive at the end of the flow. Use token to get only an access_token

If response_type=token, after the user authenticates with the provider, this will redirect them to your application callback URL while passing the access_token in the address location.hash. This is used for Single Page Apps and on Native Mobile SDKs.

client_id
required
string

Your application's Client ID.

verification_code
required
string

one-time verification-code

scope
string
Value: "openid"

The scopes which you want to request authorization for.

state
string

An opaque value the clients adds to the initial request that Dintero includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.

redirect_uri
string

The URL to which Dintero will redirect the browser after authorization has been granted by the user.

The redirect_uri value must be specified as a valid callback URL under your Client's Settings.

connection
string

The name of the connection configured to your client.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Authorize with OIDC

path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

query Parameters
audience
required
string

The unique identifier of the target API you want to access. The audience must have a Grant with OIDC configured

response_type
required
string
Value: "code"
client_id
required
string

The client_id of your application

redirect_uri
required
string

The URL to redirect after authorization has been granted by the user.

scope
string

Scope of the access request, space-separated list.

client_token
string
Example: client_token=eyJhbGci...t7P4

Authorization token to use if no authorization header is included

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Token verified by OIDC

Use this endpoint to obtains an access token by presenting its authorization grant

scopes:

  • write:accounts:/auth/users
scopes: ["write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client that has oidc configured

code
required
string
grant_type
required
string
Value: "authorization_code"
client_id
required
string
redirect_uri
string

The redirect URL which the user agent is redirected to after finishing a login.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGci...t7P4",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "user_info": {}
}

Passwordless

Passwordless connections do not require the user to remember a password. Instead, another mechanism is used to prove identity, such as a one-time code sent through email or SMS, every time the account user logs in.

  • The client_id/audience must have a grant with type authorization_code to allow sending verification-code
  • This endpoint is designed to be called from the client-side and is subjected to rate limits

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/passwordless
  • write:accounts:/auth/passwordless-sms
  • write:accounts:/auth/passwordless-email
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/passwordless","write:accounts:/auth/passwordless-sms","write:accounts:/auth/passwordless-email"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
client_id
required
string
connection
required
string
Enum: "email" "sms"

How to send the code to the user.

audience
required
string

The unique identifier of the target API you want to access.

email
string

The user's email address

type
string
Default: "customer"
Enum: "company" "customer"

Passwordless for type company/customer requires that the email is registered to a customers users

send
string
Default: "code"
Value: "code"

Use code to send a verification code.

login_session_id
string

Use login_session_id to resend the same verifcation code to an alternative connection.

Responses

Request samples

Content type
application/json
{
  • "audience": "string",
  • "client_id": "string",
  • "connection": "email",
  • "email": "string",
  • "type": "company",
  • "send": "code",
  • "login_session_id": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Passwordless Code

Passwordless connections do not require the user to remember a password. Instead, another mechanism is used to prove identity, such as a one-time code sent through email or SMS, every time the account user logs in.

Use this endpoint to generate a one-time verification-code that can be sent to the user.

The client_id/audience must have a grant with type authorization_code to allow creating a verification-code

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/passwordless/code
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/passwordless/code"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
audience
required
string

The unique identifier of the target API you want to grant the user

client_id
required
string

The client whoose grants will be granted to the user, the

user_id
required
string

The user_id / subject to grant access

Responses

Request samples

Content type
application/json
{
  • "audience": "string",
  • "client_id": "string",
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "verification_code": "string"
}

Redirect with ID token

Use this endpoint to redirect to an URL with a ID token added.

Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
redirect_uri
required
string <uri> ^https?://.*

The HTTP URL to redirect to

object <= 5 properties

Include custom claims to the ID token. Custom claims will be prefixed by ext_.

claims
Array of strings
Items Enum: "name" "email"

Specify optional claims to include in the ID token

Responses

Request samples

Content type
application/json
{
  • "redirect_uri": "http://example.com",
  • "custom_claims": {
    },
  • "claims": [
    ]
}

Response samples

Content type
application/json
{}

Revoke Token

Use this endpoint to invalidate a Refresh Token if it has been compromised.

scopes:

  • admin:accounts
  • write:accounts
  • create:accounts:auth:refresh_token
scopes: ["admin:accounts","write:accounts","create:accounts:auth:refresh_token"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "YOUR_REFRESH_TOKEN"
}

Response samples

Content type
application/json
{ }

Get Token

Use this endpoint to directly request an access_token

Client Access Token

Use HTTP Basic authentication scheme for authenticating grant_type client_credentials, use client_id/client_secret as user/password.

Code/Password Token

Use HTTP Bearer authentication scheme for authenticating grant_type authorization_code or password, where the Bearer value must be a JWT toke with access to the token endpoint.

Account User Token

Use HTTP Bearer authentication scheme for authenticating grant_type account_user_token, where the Bearer value must be a account user JWT token.

Use ID token as Bearer toke if the user was authenticated externally. The ID must include a email claim that identifies the account user.

Refresh Token

Use HTTP Bearer authentication scheme for authenticating grant_type refresh_token where the Bearer value must be an Access Token for the clients that was used to create the Refresh Token.

Multi-factor authentication (MFA)

When a request is made to the endpoint to get an access token, normally you either get an error, or you get an access token. However, when the MFA is enabled, the endpoint may return a new error with error.code: mfa_required.

When an mfa_required error is returned, the client must perform a challenge. This is done by sending a request to the auth/mfa/challenge endpoint

To verify MFA using an OOB challenge, the client must make a request to this endpoint with grant_type=mfa-oob. Include the oob_code you received from the challenge response, as well as the mfa_token you received as part of mfa_required error.

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/users
  • write:accounts:/auth/users/no-mfa
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/users","write:accounts:/auth/users/no-mfa"]
Authorizations:
clientAuthJWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
grant_type
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "grant_type": "account_user"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGci...t7P4",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "refresh_token": "string"
}

Exchange Token

Use this endpoint to exchange access_token to a sub-account

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
partner_id
required
string <^[PT]{1}\d{3}00000$> = 9 characters

An id that uniquely identifies the partner account

Request Body schema: application/json
required
account_id
required
string <^[PT]{1}\d{8}$>

The account_id to create exchange access_token for

Responses

Request samples

Content type
application/json
{
  • "account_id": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGci...t7P4",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "refresh_token": "string"
}

clients

Clients collection

Retrieve a list of all client applications

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Client

Creates a new client application.

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
name
string
description
string
client_id
string

Your client ID.

callbacks
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ],
  • "client_secret": "JYCRP/x7iBGWA1fun0J9laH5sEg5cP9g/4QivhfGzm4"
}

Get Client

Retrieves a client by its id.

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

id
required
string

The id of the client

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ]
}

Delete Client

Deletes a client and all its related assets

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

id
required
string

The id of the client

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ]
}

Rotate a client secret.

Rotate a client secret.

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

id
required
string

The id of the client

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "client_id": "string",
  • "callbacks": [
    ],
  • "client_secret": "JYCRP/x7iBGWA1fun0J9laH5sEg5cP9g/4QivhfGzm4"
}

grants

Client grants collection

Manage your Client Grants (also called Client Credentials Grants). Using Client Grants, your Client can request an access token using its credentials (a Client ID and a Client Secret). The access token then represents your Client during API calls.

Use the Grant type to limit how the grant can be used when requesting an access token. A Grant with type password can only be used when requesting an access token with grant_type set to password.

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

query Parameters
audience
string <= 1

filter client grants by audience

client_id
string <= 1

filter client grants by client_id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create client grant

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
client_id
required
string
audience
required
string
scope
required
Array of strings[ items non-empty ]
type
string
Default: "any"
Enum: "any" "authorization_code" "client_credentials" "password"

Limit the usage of the grant. A grant with grant_types set to only authorization_code cannot be used in Get Token when calling the endpoint with grant_type=client_credentials

object

Open ID connect configuration for the Grant. The option enables client to verify the identify of the End-User based on the authentication performed by an authorization server

The grant type must be set to authorization_code when configured.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "client_id": "string",
  • "audience": "https://api.dintero.com/v1/accounts/P00000000",
  • "scope": [
    ],
  • "type": "any",
  • "oidc": {}
}

Delete client grant

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

id
required
string

The id of the client grant to delete

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "client_id": "string",
  • "audience": "https://api.dintero.com/v1/accounts/P00000000",
  • "scope": [
    ],
  • "type": "any",
  • "oidc": {}
}

roles

Roles collection

Retrieve filtered list of roles that can be assigned to users.

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

query Parameters
search
string

lookup roles matching id, name and description

name
string

lookup roles by name

include_deleted
boolean
Default: false

include deleted roles in the response

limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a role

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
scope
required
Array of strings[ items non-empty ]
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Get role

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

role_id
required
string

The id of the rule to delete

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Update role

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

role_id
required
string

The id of the rule to delete

Request Body schema: application/json
required
scope
required
Array of strings[ items non-empty ]
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

Delete role

scopes:

  • admin:accounts
  • write:accounts
scopes: ["admin:accounts","write:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

role_id
required
string

The id of the rule to delete

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "order support",
  • "description": "Administrate orders",
  • "scope": [
    ]
}

keys

Get public keys

Retrieve the JSON Web Key Set (JWKS) that can be used to validate access_token

scopes:

  • admin:accounts
  • read:accounts
scopes: ["admin:accounts","read:accounts"]
Authorizations:
JWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

users

Admin users

Create User

Create a new user

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/users
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
username
required
string [ 1 .. 255 ] characters

The user's username.

password
required
string >= 8 characters

The user's password

Array of objects (AuthUserLinks)

Links to resources related to the user, links is required when MFA is enabled.

object (AuthUserMfa)

Require Multi-factor authentication (MFA) for the user

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "links": [],
  • "mfa": {
    },
  • "password": "stringst"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "links": [],
  • "mfa": {
    }
}

Update user

Update existing user with new password

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/users
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

username
required
string <= 255 characters

Username identifying the user

Request Body schema: application/json
required
password
required
string >= 8 characters

The user's password

Array of objects (AuthUserLinks)

Links to resources related to the user, links is required when MFA is enabled.

object (AuthUserMfa)

Require Multi-factor authentication (MFA) for the user

Responses

Request samples

Content type
application/json
{
  • "password": "stringst",
  • "links": [],
  • "mfa": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "links": [],
  • "mfa": {
    }
}

Delete user

Delete existing user

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/users
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

username
required
string <= 255 characters

Username identifying the user

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "links": [],
  • "mfa": {
    }
}

Change username

Update existing users username

scopes:

  • admin:accounts
scopes: ["admin:accounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

username
required
string <= 255 characters

Username identifying the user

Request Body schema: application/json
required
username
required
string [ 1 .. 255 ] characters

The user's new usernname

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "links": [],
  • "mfa": {
    }
}

challenge

Challenge request

Request a challenge for multi-factor authentication (MFA) based on the challenge types supported by the user.

The challenge_type is how the user will get the challenge and prove possession. Supported challenge types include:

  • oob: for SMS messages or out-of-band (OOB)

Use the response to request access token from the auth/token endpoint with grant_type=mfa_oob

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/mfa
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/mfa"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
challenge_type
required
string
Value: "oob"

The challenge type accepted by your application

mfa_token
required
string

The token received from mfa_required error.

oob_channel
string
Default: "sms"
Enum: "sms" "email"

The channel to use for OOB. Can only be provided when challenge_type is oob.

Responses

Request samples

Content type
application/json
{
  • "challenge_type": "oob",
  • "oob_channel": "sms",
  • "mfa_token": "string"
}

Response samples

Content type
application/json
{
  • "challenge_type": "oob",
  • "binding_method": "prompt",
  • "oob_code": "bkaiew...akas"
}

Recovery

Request a recovery for user with multi-factor authentication (MFA) enabled.

A recovery is done with two out-of-band (OOB) challenges over different channels.

Use the response to request access token from the auth/token endpoint with grant_type=mfa_oob.

A 403 status with mfa_required error will be returned on success, use the response to request a new challenge from the auth/mfa/challenge endpoint.

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/mfa
scopes: ["admin:accounts","write:accounts","write:accounts:/auth/mfa"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
challenge_type
required
string
Value: "oob"

The challenge type accepted by your application

username
required
string

The end user's identifier.

audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used in the request

oob_channel
string
Default: "sms"
Enum: "sms" "email"

The channel to use for OOB. Can only be provided when challenge_type is oob.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "challenge_type": "oob",
  • "binding_method": "prompt",
  • "oob_code": "bkaiew...akas",
  • "mfa_token": "string"
}

users

A user, aka customer, member.

Create new Customer

Create a new customer, customer_id, email and phone_number must be unique if specified. scopes:

  • admin:customers
  • write:customers
  • create:customers:/users
scopes: ["admin:customers","write:customers","create:customers:/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

customer to create

type
required
string
Default: "customer"
Enum: "customer" "company" "contact" "employee" "other"

Describe type of a user.

  • company property is required when using the type company
  • company property is only supported for users with type other or company
  • Creating or updating user with type employee or other requires admin:customers or write:customers scope.
  • User login is only available for users with type customer or company
metadata
object <= 40 properties

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. You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null

first_name
string or null
last_name
string or null
email
string or null

customer email, case insensitive duplication control prevents multiple user with same type to have equal email

customer@example.com is equal to CUStOMer@EXAMPLE.com

phone_number
string or null <^\+?[1-9]\d{1,14}$>

A phone number in E.164 number formatting.

attributes
object

Custom attributes

status
string or null

Status of the customer

favorite_store
string or null

customer favorite store

object

The source that recruited the customer

object

Customers consent for marketing in different channels

Array of objects (CustomerAddress)
object (CustomerTerm)
object

Company details, supported when type is Company

gender
string or null
date_of_birth
string or null <date>
Array of objects

The users that it is a contact for, supported when type is contact

customer_id
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces) An auto-generated customer_id will be created if no customer_id is provided.

password
string [ 8 .. 255 ] characters

The customer password. The caller must have scope write:accounts:/auth/users when password is included in the body

pin
string = 6 characters ^\d{6}$

6 digit customer pin, can only used for MFA login. The caller must have scope write:accounts:/auth/users when pin is included in the body

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string",
  • "password": "stringst",
  • "pin": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

User exist

Check if there is users that match the parameters. The result will match all parameters with AND. This endpoint must be enabled from PUT /customers/settings scopes:

  • admin:customers
  • read:customers
  • public:customers
scopes: ["admin:customers","read:customers","public:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
email
string

lookup customer by email

phone_number
string

lookup customer by phone_number

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Customer collection

Get all customers, limited by parameters. The result will match all parameters with AND. Search is done by prefix match, and + in phone_number/email must be URL encoded, (+4799999999 => %2B4799999999)

Users with type contact are by default excluded from the result, use type=contact or type=any to include contact users

The response from a request that match contact users will include the users that are linked from the contact

scopes:

  • admin:customers
  • read:customers
scopes: ["admin:customers","read:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
token_value
string

lookup customers by token value

token_type
string

lookup customer by token type

email
string

lookup customer by email

phone_number
string

lookup customer by phone_number

type
string
Enum: "customer" "company" "contact" "employee" "other" "any"

lookup customer by type

search
string

lookup customer where search term match name, phone number, customer_id or email. The search term will be matched with the user details

tag_id
string

lookup customers by tag id

include_deleted
boolean
Default: false

include deleted customers in the response. A deleted user will only have an id/customer_id, created_at/created_by and deleted_at/deleted_by set All other details of a customer, like email or phone_number will be deleted.

attributes_keys
Array of strings <= 4 items

include customers that has all the attributes.

attributes_values
Array of strings <= 4 items

Combine with attributes_keys to include customers with match on attribute values

since_datetime
string <date-time>

lookup customers that has been added or modified since an ISO timestamp. NOTE: this parameter can't be combined with starting_after parameter. Retrieve next page by updating since_datetime to the latest updated_at value found in the result

limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

total
boolean
Default: false

include total-count header in the response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Customer details

Customer details scopes:

  • admin:customers
  • read:customers
  • user:customers
  • user:customers:/customer/details
scopes: ["admin:customers","read:customers","user:customers","user:customers:/customer/details"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

Update Customer

Update customer properties, properties not included in the body will remain unchanged. scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Request Body schema: application/json
required

Customer update

first_name
string or null
last_name
string or null
email
string or null

customer email, case insensitive duplication control prevents multiple user with same type to have equal email

customer@example.com is equal to CUStOMer@EXAMPLE.com

phone_number
string or null <^\+?[1-9]\d{1,14}$>

A phone number in E.164 number formatting.

attributes
object

Custom attributes

status
string or null

Status of the customer

favorite_store
string or null

customer favorite store

object

The source that recruited the customer

object

Customers consent for marketing in different channels

type
string
Default: "customer"
Enum: "customer" "company" "contact" "employee" "other"

Describe type of a user.

  • company property is required when using the type company
  • company property is only supported for users with type other or company
  • Creating or updating user with type employee or other requires admin:customers or write:customers scope.
  • User login is only available for users with type customer or company
Array of objects (CustomerAddress)
object (CustomerTerm)
object

Company details, supported when type is Company

gender
string or null
date_of_birth
string or null <date>
Array of objects

The users that it is a contact for, supported when type is contact

password
string [ 8 .. 255 ] characters

The customer password. The caller must have scope write:accounts:/auth/users when password is included in the body

pin
string = 6 characters ^\d{6}$

6 digit customer pin, can only be used for MFA login. The caller must have scope write:accounts:/auth/users when pin is included in the body

Responses

Request samples

Content type
application/json
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "password": "stringst",
  • "pin": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

Delete customer

Delete single customer scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
delete_tokens
boolean
Default: false

Delete all tokens owned by the customer

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

Change customer_id

Update customer_id for an customer warning: Any external resources "owned" by the user, i.e receipts, discounts etc. will not be updated with the new customer_id. A new metadata property dintero_change_customer_id_{timestamp}.{hash} will be added everytime the customer_id is changed Following data will be included in the metadata property

  • created_at
  • created_by
  • old
  • new scopes:
  • admin:customers
  • admin:accounts
scopes: ["admin:customers","admin:accounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Request Body schema: application/json
required

Customer update

customer_id
string [ 1 .. 255 ] characters

New customer_id (must not have trailing or leading spaces).

Responses

Request samples

Content type
application/json
{
  • "customer_id": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "customer@example.com",
  • "phone_number": "+4799999999",
  • "attributes": { },
  • "status": "string",
  • "favorite_store": "string",
  • "enrolled_by": {},
  • "marketing_consent": {
    },
  • "type": "customer",
  • "addresses": [
    ],
  • "term": {
    },
  • "company": {
    },
  • "gender": "male",
  • "date_of_birth": "1990-09-20",
  • "contact_for": [
    ],
  • "customer_id": "string"
}

tokens

Get token events

Get the token events scopes:

  • admin:customers
  • read:customers
scopes: ["admin:customers","read:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

since_datetime
string <date-time>

Only token events added/updated at or after this time is returned NOTE: this parameter can't be combined with starting_after parameter. Retrieve next page by updating since_datetime to the latest updated_at value found in the result.

deleted_since
string <date-time>

return only token events that has been deleted

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete token events

Delete the connection between token (type/value) and list of events. Include an event in the request to store the reason for the request scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
required
object (TokenTypeValue)

Lookup by token type and value

object

Record an delete event, the status will be set to DELETED.

Responses

Request samples

Content type
application/json
{
  • "token": {
    },
  • "event": {
    }
}

Find / Add token events

Find details about a token, inclusive details about any customer the token belongs to and any token events recorded Include event in the request to update the status of the token scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
required
object (TokenTypeValue)

Lookup by token type and value

object (TokenEvent)

Record event data about a token An event can be created before the customer exist and before the token has been added to the customer

Responses

Request samples

Content type
application/json
{
  • "token": {
    },
  • "event": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer": {
    },
  • "token": {
    },
  • "status": "OPT_OUT",
  • "events": [
    ]
}

Token collections

Get all tokens for a Customer scopes:

  • admin:customers
  • read:customers
  • user:customers
scopes: ["admin:customers","read:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
type
string

filter tokens on type

limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

total
boolean
Default: false

include total-count header in the response

include_deleted
boolean
Default: true

include deleted tokens in the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new Token

Create a new customer token scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
delete_token_events
boolean
Default: false

delete all token events recorded on token type/value before creating new customer token

Request Body schema: application/json
required

customer token to add

type
required
string non-empty

identifies how or who is resposible for the token value

value
required
string non-empty
token_id
string [ 1 .. 255 ] characters

The token id you have defined for the token. (must not have trailing or leading spaces). An auto-generated token_id will be created if no token_id is provided.

metadata
object

Additional metadata about the token or the entity the token was created from

Responses

Request samples

Content type
application/json
{
  • "token_id": "string",
  • "type": "sha1:email",
  • "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "token_id": "string",
  • "type": "sha1:email",
  • "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
  • "metadata": {
    }
}

Delete customer token

Delete Token

scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

tid
required
string <= 255 characters

The token id you have defined for the token. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "token_id": "string",
  • "type": "sha1:email",
  • "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
  • "metadata": {
    }
}

password

Change password

Specify the email address of the user whose password you would like to reset. If the call is successful, the user will receive an email prompting them to change their password. The caller must have scope write:accounts:/auth/users to perform a change password request. scopes:

  • write:accounts:/auth/users
scopes: ["write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource.

email
required
string
type
required
string
Enum: "customer" "company"

user type to login, required as users with different type can share email

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "audience": "string",
  • "type": "customer"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Login with email/password

Login a customer user, the caller must have scope write:accounts:/auth/users. If MFA is enabled on account, use write:accounts:/auth/users/no-mfa to skip MFA. scopes:

  • write:accounts:/auth/users
  • write:accounts:/auth/users/no-mfa
scopes: ["write:accounts:/auth/users","write:accounts:/auth/users/no-mfa"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

credentials

audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource.

type
required
string
Enum: "customer" "company"

user type to login, required as users with different type can share email

password
required
string [ 4 .. 255 ] characters

The customer pin or password. The caller must have scope write:accounts:/auth/users or write:accounts:/auth/users/no-mfa when password is included in the body

email
string

Required if ident_type and ident is not set

ident_type
string
Enum: "phone_number" "email"

Required if email is not set

ident
string

Email or phone_number, depending on the ident_type.

Required if email is not set.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "ident_type": "phone_number",
  • "ident": "string",
  • "audience": "string",
  • "type": "customer",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGci...t7P4",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "refresh_token": "string"
}

Login with MFA

Initiate a Multi-Factor Authentication for a customer user, the caller must have scope write:accounts:/auth/users to perform a login. Post the ident_type, along with the ident and secret. The server will return a challenge response specifying the challenge_type that will have to be completed to when getting an access token from the POST /v1/accounts/{oid}/auth/token endpoint. scopes:

  • write:accounts:/auth/users
scopes: ["write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

credentials

audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource.

ident_type
required
string
Enum: "phone_number" "email"
ident
required
string

Email or phone_number, depending on the ident_type.

type
required
string
Enum: "customer" "company"

user type to login, required as users with different type can share email

secret
required
string

The customers pin or password.

Responses

Request samples

Content type
application/json
{
  • "ident_type": "phone_number",
  • "ident": "string",
  • "audience": "string",
  • "type": "customer",
  • "secret": "string"
}

Response samples

Content type
application/json
{}

MFA recovery

Initiate a Multi-Factor Authentication recovery login for a customer user that has forgotten/lost their secret. Specify the ident_type and the ident (email or phone_number) of the user. If the call is successful, the user will get an email with an one time recovery code that has to be submitted to the mfa_recovery endpoint. When a valid one time recovery has been posted the server response with a regular MFA challenge. Once authenticated the password or pin can be changed by updating the customer. scopes:

  • write:accounts:/auth/users
scopes: ["write:accounts:/auth/users"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource.

ident_type
required
string
Enum: "phone_number" "email"
ident
required
string

Email or phone_number, depending on the ident_type.

type
required
string
Enum: "customer" "company"

user type to login, required as users with different type can share email

Responses

Request samples

Content type
application/json
{
  • "ident_type": "phone_number",
  • "ident": "string",
  • "audience": "string",
  • "type": "customer"
}

Response samples

Content type
application/json
{
  • "links": [
    ],
  • "binding_method": "prompt",
  • "oob_code": "bkaiew...akas",
  • "mfa_token": "string",
  • "challenge_type": "oob"
}

communication

Customer email/phone_number Status

Get the status of customer email / phone_number communication scopes:

  • admin:customers
  • read:customers
  • user:customers
scopes: ["admin:customers","read:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "communication": {
    }
}

Verify Customer email/phone_number

Verify customer email/phone_number field. Consist of to steps:

  • send verification code to the customer (sms or email)
  • verify the email/phone_number by posting verification code sent to customer scopes:
  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

field
required
string
Enum: "email" "phone_number"

field to verify

operation
required
string
Enum: "send-verification-code" "confirm-verification-code"

Verify operation

Request Body schema: application/json

verification code

code
string

Verification code sent to customer

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

tags

Tags collection

Get all customer tags (also known as groups). scopes:

  • admin:customers
  • read:customers
scopes: ["admin:customers","read:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new Tag

Create a tag scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

customer tag add

tag
required
string

tag value

metadata
object

A set of key/value pairs that you can attach to a tag.

Responses

Request samples

Content type
application/json
{
  • "tag": "VIP",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "tag": "VIP",
  • "metadata": { }
}

Delete Tag

Delete a tag. A deleted tag is removed from customer tags scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

tag_id
required
string <uuid>

tag id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "tag": "VIP",
  • "metadata": { }
}

Update Customer Tags

Update Customer Tags scopes:

  • admin:customers
  • write:customers
  • user:customers
scopes: ["admin:customers","write:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Request Body schema: application/json
required

tag ids to set

Array
string <uuid>

list of tag ids

Responses

Request samples

Content type
application/json
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

Response samples

Content type
application/json
[
  • {
    }
]

Tag collection

Get tags for a customer scopes:

  • admin:customers
  • read:customers
  • user:customers
scopes: ["admin:customers","read:customers","user:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

terms

Create new Terms

Create customer terms and conditions scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

terms to create

terms
required
string

Responses

Request samples

Content type
application/json
{
  • "terms": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "terms": "string"
}

Terms collection

Get all customer terms and conditions scopes:

  • admin:customers
  • read:customers
  • public:customers
scopes: ["admin:customers","read:customers","public:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

include_deleted
boolean
Default: false

include deleted terms in the response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Terms details

Get single terms and conditions scopes:

  • admin:customers
  • read:customers
  • public:customers
scopes: ["admin:customers","read:customers","public:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

tid
required
string <uuid>

terms id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "terms": "string"
}

Delete Term

Delete the customer term scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

tid
required
string <uuid>

terms id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "terms": "string"
}

settings

Customers settings

Get customers settings

scopes:

  • admin:customers
  • read:customers
  • public:customers
scopes: ["admin:customers","read:customers","public:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Responses

Response samples

Content type
application/json
{
  • "users": {
    },
  • "auto_tokens": {
    },
  • "tokens": {
    },
  • "attributes": [
    ]
}

Update settings

Update customers settings

scopes:

  • admin:customers
  • write:customers
scopes: ["admin:customers","write:customers"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

customers settings

object

customers user configurations

object

Automatically generate tokens for these properties on the customer

object

tokens configuration

Array of objects

user attributes

Responses

Request samples

Content type
application/json
{
  • "users": {
    },
  • "auto_tokens": {
    },
  • "tokens": {
    },
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "users": {
    },
  • "auto_tokens": {
    },
  • "tokens": {
    },
  • "attributes": [
    ]
}

rules

Public Discount collection

Get all discounts available for any customer given current date, result will exclude expired and inactive discounts

Use value of ref_id as parameter value of starting_after

scopes:

  • admin:discounts
  • read:discounts
  • public:discounts
scopes: ["admin:discounts","read:discounts","public:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

no_customer_id
boolean
Default: false

List rules available for purchase where no customer id is provided.

campaign_id
Array of strings

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new discount

Create a new discount for an account.

A new discount will be unavailable for purchases until the discount is given to one or more customer.

Discount can be given to a customer by either adding a automation to the discount that will grant the discount to the customer from events received or by adding customers to the discount.

See Discount Examples

scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

Discount to create

required
object (Requirement)

Discount base requirement

required
object (Reward)
campaign_id
string

The campaign the rule belongs to

active
boolean
Default: true

the discount is active and can be available for purchase (if given to any or all customers)

private
boolean
Default: false

the discount will be excluded from public discount collection (GET /discounts/public/rules).

name
string
receipt_text
string

Text that should be used when displaying the discount, e.g. on receipt

visible_from
string <date-time>

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
string
object (Limitation)
metadata
object <= 10 properties

Additional metadata about the discount

Metadata prefixed with dintero:exclude:public: will be excluded when listing the rules from the public endpoint

and included in all other endpoints that returns discount rules

Array of objects (Links) [ items <= 10 items ]

Links to resources related to the discount

Responses

Request samples

Content type
application/json
{
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": []
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8",
  • "type": "item",
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": []
}

Discount collection

List discounts available for the account scopes:

  • admin:discounts
  • read:discounts
scopes: ["admin:discounts","read:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

since_datetime
string <date-time>

Only discounts added/updated/delete at or after this time is returned. NOTE: this parameter can't be combined with starting_after parameter. Retrieve next page by updating since_datetime to the latest updated_at value found in the result.

purchase_from
string <date-time>

Only discounts with requirement purchase_from at or after this time is returned.

purchase_to
string <date-time>

Only discounts with requirement purchase_to at or before this time is returned.

state
string
Default: "all"
Enum: "all" "available" "deleted" "inactive"

Indicate the state of the discounts to return

campaign_id
Array of strings
include
Array of strings
Items Value: "statistics"

Additional fields to include for each discount

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Discount details

Get more details about a discount, includes statistics about the discount scopes:

  • admin:discounts
  • read:discounts
scopes: ["admin:discounts","read:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

did
required
string <uuid>

An UUID that uniquely identifies the discount

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8",
  • "type": "item",
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": [],
  • "statistics": {
    }
}

Update Discount

Update discount details.

Caution: Update of non-meta properties, properties that changes requirement or limitation can create conflict with the usage history of the discount.

Example is to change requirement.item.items, such change would mean that purchases before the change would not be correcly rewarded given the new version of the discount.

We recomment to limit the update of a discount to meta only properties if the discount has previously been used in a purchase.

Update on requirement purchase_to is only supported when the new value that is after current value.

Update of requirement purchase_from and reward is not supported.

Update discount.active to toggle if an discount is active and available for purchase.

Update discount.private to toggle if an discount is included in public discount collection if given to all customers

scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

did
required
string <uuid>

An UUID that uniquely identifies the discount

Request Body schema: application/json
required

Discount properties to update

campaign_id
string or null

The campaign the rule belongs to, use null to remove the rule from the campaign.

active
boolean
Default: true

the discount is active and can be available for purchase

private
boolean

the discount is private and will not be included in public discount collection

Array of objects (Links) [ items <= 10 items ]

Links to resources related to the discount

object (Limitation)
object

Discount base requirement

object
description
string
metadata
object <= 10 properties

Additional metadata about the discount

name
string
receipt_text
string

Text that should be used when displaying the discount, e.g. on receipt

Responses

Request samples

Content type
application/json
{
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "links": [],
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "description": "Gjør et Stablestol kupp!",
  • "metadata": {
    },
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8",
  • "type": "item",
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": [],
  • "statistics": {
    }
}

Delete discount

Delete a discount

  • Customer that has previously received the discount will not be able to use it on purchases.
  • rules automations belonging to the discount will be deleted

scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

did
required
string <uuid>

An UUID that uniquely identifies the discount

Responses

Response samples

Content type
application/json
{
  • "statistics": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8",
  • "type": "item",
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": []
}

customers

Manage customers

Update customer discount ref

Add stamps and usage to a discount ref. scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

ref_id
required
string

A string that uniquely identifies a customer discount reference

Request Body schema: application/json
required

update usage, stamps and amount

object (UsageRefWrite)

Responses

Request samples

Content type
application/json
{
  • "usage_ref": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8",
  • "type": "item",
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": [],
  • "statistics": {
    },
  • "ref_id": "string"
}

Get customer discount ref

Get a customer discount ref. scopes:

  • admin:discounts
  • read:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

ref_id
required
string

A string that uniquely identifies a customer discount reference

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8",
  • "type": "item",
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": [],
  • "statistics": {
    },
  • "ref_id": "string"
}

Delete customer discount ref

Delete a customer discount ref. The discount will no longer be available on purchase (Post receipt for discount)

scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

ref_id
required
string

A string that uniquely identifies a customer discount reference

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8",
  • "type": "item",
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": [],
  • "statistics": {
    },
  • "ref_id": "string",
  • "debit_balance": 0
}

Customer discounts collection

Get all discounts available for a customer, result will exclude expired and inactive discounts

Expired discounts are:

  • discount used up (customer has allready used it) and there was a limitation on the discount that prevents more use.
  • discount requirement purchase periode is in the past
  • discount that has been deleted

Inactive discounts are:

  • discount with active property set to false.

Use value of ref_id as parameter value of starting_after

scopes:

  • admin:discounts
  • read:discounts
  • user:discounts
scopes: ["admin:discounts","read:discounts","user:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add customers

Give the Discount to one or more customers

scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

did
required
string <uuid>

An UUID that uniquely identifies the discount

Request Body schema: application/json
required

Customers to give the discount to

customers
required
Array of strings

Array of customer IDs (must not have trailing or leading spaces)

Following values are reserved:

  • * give the discount to purchase with any customer_id.
  • / give the discount to purchase with no customer_id.
offering_constraint_id
string

Use the offering_constraint_id to limit customers to only receive the discount once for a given offering_constraint_id value. i.e. a customer that is given the same discounts in multiple requests with the same offering_constraint_id will only have one discount available.

Responses

Request samples

Content type
application/json
{
  • "offering_constraint_id": "stamp-2020",
  • "customers": [
    ]
}

Response samples

Content type
application/json
{
  • "statistics": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8",
  • "type": "item",
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": []
}

Get discount customers (refs)

Get list of customers refs for a discount. A ref is an instant of discount given to a customer or all customers. See Add customers

scopes:

  • admin:discounts
  • read:discounts
scopes: ["admin:discounts","read:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

did
required
string <uuid>

An UUID that uniquely identifies the discount

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 10

A limit on the number of refs to be returned. Limit can range between 1 and 1000, the default is 10 items.

starting_after
string

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.

state
string
Default: "all"
Enum: "all" "available" "deleted" "inactive"

limit by state of customer ref, note, a customer ref will continue to be active after the discount has been deleted. Use state inactive to list all discount where active is set to false.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove customers

Remove Discount from one or more customers

scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

did
required
string <uuid>

An UUID that uniquely identifies the discount

Request Body schema: application/json
required

Customers to give the discount to ### Use value '*' to remove the discounts from all customers ###

customers
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "customers": [
    ]
}

Response samples

Content type
application/json
{
  • "statistics": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "active": true,
  • "private": false,
  • "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8",
  • "type": "item",
  • "name": "Spar 100,-",
  • "receipt_text": "Mai Salg",
  • "visible_from": "2019-08-24T14:15:22Z",
  • "description": "Gjør et Stablestol kupp!",
  • "limitation": {
    },
  • "requirement": {
    },
  • "reward": {
    },
  • "metadata": {
    },
  • "links": []
}

Get discount ref usages

Get list of discount refs usages. scopes:

  • admin:discounts
  • read:discounts
scopes: ["admin:discounts","read:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

did
required
string <uuid>

An UUID that uniquely identifies the discount

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 10

A limit on the number of refs to be returned. Limit can range between 1 and 1000, the default is 10 items.

starting_after
string

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

use discounts

Post receipt for discount

Find discounts available for the receipt

Active discounts

  • customer_id will be used to find active discounts for the purchase.
  • customer.token will be used to resolve customer_id if no customer_id is provided.
  • No discounts will be given if the token does not resolve to any customer_id.
  • A receipt with no customer_id and no customer.token will only be applicable for active discounts given to / (see)

Requirement of the receipt

  • all items must have eligible_for_discount set to enable for discount
  • all items must have a positive gross_amount to qualify for discount
  • a net base discount reward requires the receipt to include existing discounts as discount_lines (on item) in order to calculate net

A receipt that qualified for discount will have the is_change property set to true. Any items that has received a discount will be flagged by is_change and have one or more new entries to its discount_lines.

The receipt discounts list will be populated with all discounts the receipt is qualified to receive

scopes:

  • admin:discounts
  • write:discounts
  • write:discounts:/available_for_receipt
scopes: ["admin:discounts","write:discounts","write:discounts:/available_for_receipt"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

receipt

required
object (Store)
receipt_id
required
string
purchase_at
required
string <date-time>

The date and time for the receipt purchase

Array of objects (DiscountRefs)

List all discounts referenced in discount_lines

Array of objects (ReceiptItem)
object

Details for the delivery

customer_id
string <= 255 characters

The customer id identifying the customer. (must not have trailing or leading spaces)

object

The customer, owner of the receipt

gross_amount
integer

Monetary amount in smallest unit for the currency before discounts

gross_amount_dwh
string

Monetary amount in smallest unit for the currency before discounts with decimal

net_amount
integer

Monetary amount in smallest unit for the currency after discounts

net_amount_dwh
string

Monetary value in smallest unit for the currency after discounts with decimal

round_off_to_coin
integer
currency
string

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

order_number
string
transaction_date
string <date-time>
amount_due
integer

How much more need to be paid before the transaction is completed. Monetary amount in smallest unit for the currency

amount_due_dwh
string

Monetary value with decimal

no_of_items
number

How many items did the customer buy

is_changed
boolean

Discount applied to gross amount

transaction_id
string
total_discount
integer
total_manual_discount_amount
integer

Monetary amount in smallest unit for the currency

total_manual_percentage_discount
integer
operator_id
string

POS user

operator_name
string

Name of the POS user

salesperson_id
string

ID of the POS user

salesperson_name
string
entry_status
string
Enum: "None" "Voided" "Posted" "Concluded" "Cancelled" "OnHold" "Training"

Status for the transaction

comment
string
Array of objects (TaxItem)

Breakdown of the tax to different tax groups

Array of objects (PaymentItem)
Array of objects (InfoCodeItem)
receipt_text
string
discount_code
Array of strings
Array of objects (ExtraInfo)

Responses

Request samples

Content type
application/json
{
  • "discounts": [
    ],
  • "store": {
    },
  • "items": [
    ],
  • "receipt_id": "714118",
  • "delivery": {
    },
  • "customer_id": "C13db4f63",
  • "customer": {
    },
  • "gross_amount": 59800,
  • "gross_amount_dwh": "59800.01",
  • "net_amount": 47840,
  • "net_amount_dwh": "47840.01",
  • "round_off_to_coin": 100,
  • "currency": "NOK",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "order_number": "order12345",
  • "transaction_date": "2019-08-24T14:15:22Z",
  • "amount_due": 2050,
  • "amount_due_dwh": "2050.10",
  • "no_of_items": 4,
  • "is_changed": true,
  • "transaction_id": "SC999-9991-1828",
  • "total_discount": 0,
  • "total_manual_discount_amount": 0,
  • "total_manual_percentage_discount": 0,
  • "operator_id": "000210",
  • "operator_name": "Ole Anders",
  • "salesperson_id": "000111",
  • "salesperson_name": "Jesper",
  • "entry_status": "None",
  • "comment": "Kunden ønsker mer for info",
  • "tax_lines": [
    ],
  • "payments": [
    ],
  • "infocode_items": [
    ],
  • "receipt_text": "string",
  • "discount_code": [
    ],
  • "extra_info": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "discounts": [
    ],
  • "store": {
    },
  • "items": [
    ],
  • "receipt_id": "714118",
  • "delivery": {
    },
  • "customer_id": "C13db4f63",
  • "customer": {
    },
  • "gross_amount": 59800,
  • "gross_amount_dwh": "59800.01",
  • "net_amount": 47840,
  • "net_amount_dwh": "47840.01",
  • "round_off_to_coin": 100,
  • "currency": "NOK",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "order_number": "order12345",
  • "transaction_date": "2019-08-24T14:15:22Z",
  • "amount_due": 2050,
  • "amount_due_dwh": "2050.10",
  • "no_of_items": 4,
  • "is_changed": true,
  • "transaction_id": "SC999-9991-1828",
  • "total_discount": 0,
  • "total_manual_discount_amount": 0,
  • "total_manual_percentage_discount": 0,
  • "operator_id": "000210",
  • "operator_name": "Ole Anders",
  • "salesperson_id": "000111",
  • "salesperson_name": "Jesper",
  • "entry_status": "None",
  • "comment": "Kunden ønsker mer for info",
  • "tax_lines": [
    ],
  • "payments": [
    ],
  • "infocode_items": [
    ],
  • "receipt_text": "string",
  • "discount_code": [
    ],
  • "extra_info": [
    ]
}

Claim collections

Get all claims, limited by parameters. The result will match all parameters with AND

scopes:

  • admin:discounts
  • read:discounts
  • read:discounts:/available_for_receipt
scopes: ["admin:discounts","read:discounts","read:discounts:/available_for_receipt"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

ref
string

filter claims by ref

customer_id
string

filter claims by customer_id

total
boolean
Default: false

include total-count header in the response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Claim discounts

Claim discount rewards, checks will be done to ensure that all discount limitation are uphold

Note, only the following discount limitation will affect the success of a claim

  • discount_reward_usage
  • discount_repeat_usage

scopes:

  • admin:discounts
  • write:discounts
  • write:discounts:/available_for_receipt
scopes: ["admin:discounts","write:discounts","write:discounts:/available_for_receipt"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

discounts to claim

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

required
Array of objects non-empty

Discounts to claim

purchase_at
required
string <date-time>

The date and time for the purchase the claim is done for.

ref
string

an external reference for the claim. Must be unique for the claim, reuse of ref will result in conflict

type
string

an external type for the claim

Responses

Request samples

Content type
application/json
{
  • "ref": "transactionid1",
  • "type": "pos",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "customer_id": "string",
  • "discounts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "ref": "transactionid1",
  • "type": "pos",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "customer_id": "string",
  • "discounts": [
    ]
}

Delete claim

Release claim on discounts, revert previously claimed discount and make them available for future purchase

scopes:

  • admin:discounts
  • write:discounts
  • write:discounts:/available_for_receipt
scopes: ["admin:discounts","write:discounts","write:discounts:/available_for_receipt"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

claim_id
required
string

A string that uniquely identifies claim

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "ref": "transactionid1",
  • "type": "pos",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "customer_id": "string",
  • "discounts": [
    ]
}

Get claim

Get details about a claim

scopes:

  • admin:discounts
  • read:discounts
  • read:discounts:/available_for_receipt
scopes: ["admin:discounts","read:discounts","read:discounts:/available_for_receipt"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

claim_id
required
string

A string that uniquely identifies claim

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "ref": "transactionid1",
  • "type": "pos",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "customer_id": "string",
  • "discounts": [
    ]
}

Post event

Send an Event to the service.

  • rules automations will receive the event and give its discount to the customer found in the event

  • Token received will be stored to support resolving customer from token when handling discounts available for receipt

    scopes:

    • admin:discounts
    • write:discounts
    • write:discounts:/events
scopes: ["admin:discounts","write:discounts","write:discounts:/events"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

header Parameters
event
required
string
Enum: "token_add" "token_remove" "receipt_add"

The event type that was sent

event-delivery
required
string <uuid>

UUID to identify the payload and event being sent.

Request Body schema: application/json
required

The event payload, e.g. a Customer, Receipt or Token

object (Receipt)
object

Responses

Request samples

Content type
application/json
{
  • "receipt": {
    },
  • "token": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

campaigns

Create new campaign

Create a new campaign to group discount rules

scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

Campaign to create

name
required
string
campaign_id
string <= 255 characters
description
string
private
boolean
Default: false

The campaign is private and will be excluded from public rules when filtered by campaign_id

GET /discounts/public/rules

metadata
object <= 10 properties

Additional metadata about the campaign

Responses

Request samples

Content type
application/json
{
  • "campaign_id": "string",
  • "name": "string",
  • "description": "string",
  • "private": false,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "name": "string",
  • "description": "string",
  • "private": false,
  • "metadata": {
    }
}

Campaigns collection

List campaigns

scopes:

  • admin:discounts
  • read:discounts
scopes: ["admin:discounts","read:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

state
string
Default: "all"
Enum: "all" "public" "private" "deleted"

Indicate the state of the campaign to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Campaign details

Get more details about a campaign

scopes:

  • admin:discounts
  • read:discounts
scopes: ["admin:discounts","read:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

campaign_id
required
string <= 255 characters

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "name": "string",
  • "description": "string",
  • "private": false,
  • "metadata": {
    }
}

Update Campaign

Update campaign details. Undeletes a deleted campaign.

scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

campaign_id
required
string <= 255 characters
Request Body schema: application/json
required

Campaign properties to update

name
string
description
string
private
any

The campaign is private and will be excluded from public rules when filtered by campaign_id

GET /discounts/public/rules

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "private": null
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "name": "string",
  • "description": "string",
  • "private": false,
  • "metadata": {
    }
}

Delete campagn

Delete a campagn.

Deleting a campagn does not affect its discount rules. i.e. active campagn rules will continue to be active after deleting the campagn

scopes:

  • admin:discounts
  • write:discounts
scopes: ["admin:discounts","write:discounts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

campaign_id
required
string <= 255 characters

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "campaign_id": "string",
  • "name": "string",
  • "description": "string",
  • "private": false,
  • "metadata": {
    }
}

rules

Manage automation rules

Create new automation

Create a discount automation to apply on events received.

A automation can be used to automate the task of giving discount to customers. The customer found in the event will receive the discount.

Welcome discount: give discount to new user

{
  "requirement": {
    "events": ["customer_add"],
    "automation_from": "2018-05-07T08:54:31Z",
    "automation_to": "2018-06-07T08:54:31Z"
  },
  "actions": [
    {
      "type": "discount",
      "id": "cae3e485-0e15-4afa-bc66-472f843efb84"
    }
  ]
}

Purchase discount: give discount on first purchase at store

{
  "name": "purchase at store sc029",
  "requirement": {
    "events": ["receipt_add"],
    "automation_from": "2018-05-07T08:54:31Z",
    "automation_to": "2018-06-07T08:54:31Z",
    "filters": {
      "$.store.id": ["sc029"]
    }
  },
  "actions": [
    {
      "type": "discount",
      "id": "cae3e485-0e15-4afa-bc66-472f843efb84"
    }
  ],
  "limitation": {
    "automation_repeat": 1
  }
}

scopes:

  • admin:automations
  • write:automations
scopes: ["admin:automations","write:automations"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

Automation to create

required
object
required
Array of objects (AutomationAction) = 1 items

Actions to perform if the automation is triggered (given events, limitation and filter)

name
string

Optinal name for the automation rule

description
string

Optional description for the automation rule

object

Responses

Request samples

Content type
application/json
{
  • "name": "Company Automation",
  • "description": "Automation for non blocked companies with postal_code 0342 or 6901",
  • "requirement": {
    },
  • "limitation": {
    },
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "Company Automation",
  • "description": "Automation for non blocked companies with postal_code 0342 or 6901",
  • "requirement": {
    },
  • "limitation": {
    },
  • "actions": [
    ]
}

Automation collection

Get available automations for the account

scopes:

  • admin:automations
  • read:automations
scopes: ["admin:automations","read:automations"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

state
string
Default: "all"
Enum: "all" "available" "deleted"

Indicate the state of the automation to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete automation

Delete an automation rule.

scopes:

  • admin:automations
  • write:automations
scopes: ["admin:automations","write:automations"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

arid
required
string <uuid>

An UUID that uniquely identifies the automation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "Company Automation",
  • "description": "Automation for non blocked companies with postal_code 0342 or 6901",
  • "requirement": {
    },
  • "limitation": {
    },
  • "actions": [
    ]
}

Automation details

Get details about an automations

scopes:

  • admin:automations
  • read:automations
scopes: ["admin:automations","read:automations"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

arid
required
string <uuid>

An UUID that uniquely identifies the automation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "name": "Company Automation",
  • "description": "Automation for non blocked companies with postal_code 0342 or 6901",
  • "requirement": {
    },
  • "limitation": {
    },
  • "actions": [
    ]
}

catalogs

Catalogs collection

Get catalogs from account based on query parameters

scopes:

  • admin:products
  • write:products
  • read:products
scopes: ["admin:products","write:products","read:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

Responses

Response samples

Content type
application/json
{
  • "catalogs": [
    ],
  • "starting_after": "string"
}

Create new catalog

Create a new product catalog

scopes:

  • admin:products
  • write:products
scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

catalogs

catalog_id
string <= 255 characters

The id you have defined for the catalog. (must not have trailing or leading spaces). An auto-generated catalog_id will be created if no catalog_id is provided

catalog_name
string

The catalog's name that will be shown customers

Responses

Request samples

Content type
application/json
{
  • "catalog_name": "Sommer"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "catalog_id": "S23",
  • "catalog_name": "Sommer"
}

Update catalog

Update an existing catalog

scopes:

  • admin:products
  • write:products
scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

catalog_id
required
string <= 255 characters

An id that uniquely identifies the catalog. (must not have trailing or leading spaces)

Request Body schema: application/json
required

catalog

catalog_name
string

The catalog's name that will be shown customers

Responses

Request samples

Content type
application/json
{
  • "catalog_name": "Sommer"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "catalog_id": "S23",
  • "catalog_name": "Sommer"
}

Delete catalog

Delete catalog and all corresponding products

scopes:

  • admin:products
  • write:products
scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

catalog_id
required
string <= 255 characters

An id that uniquely identifies the catalog. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "catalog_id": "S23",
  • "catalog_name": "Sommer"
}

products

Products collection

Get products in a catalog based on query parameters

scopes:

  • admin:products
  • write:products
  • read:products
scopes: ["admin:products","write:products","read:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

catalog_id
required
string <= 255 characters

An id that uniquely identifies the catalog. (must not have trailing or leading spaces)

query Parameters
product_id
string

A string that uniquely identifies the product. (must not have trailing or leading spaces)

product_name
string

Lookup on product name

limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

Responses

Response samples

Content type
application/json
{
  • "products": [
    ],
  • "starting_after": "string"
}

Create new product

Create a new product

scopes:

  • admin:products
  • write:products
scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

catalog_id
required
string <= 255 characters

An id that uniquely identifies the catalog. (must not have trailing or leading spaces)

Request Body schema: application/json
required

product to create

product_name
string

The products name which is shown to customers

description
string
is_virtual_product
boolean
Default: false
unit_gross_price
integer
unit
string

Unit type

currency
string

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

starting_at
string <date-time>

The product will not be visible until this time

stopping_at
string <date-time>

The product will not be visible after this time

object (Dimension)

Identify item attributes, such as size and color

Array of objects (Images) [ items <= 10 items ]

Links to images of product

Array of objects (Location)

All locations connected to the product

product_id
string

The id to define the product. An auto-generated product_id will be created if no product_id is provided

Array of objects

Array containing relevant product groups and sub-groups to be upserted. New groups will be inserted, existing groups will be updated and deleted groups will be revived.

Responses

Request samples

Content type
application/json
{
  • "product_name": "Stablestol",
  • "description": "Stablestol for utendørsbruk",
  • "is_virtual_product": false,
  • "unit_gross_price": 10900,
  • "unit": "stk",
  • "currency": "NOK",
  • "starting_at": "2019-08-24T14:15:22Z",
  • "stopping_at": "2019-08-24T14:15:22Z",
  • "dimension": {
    },
  • "images": [],
  • "locations": [
    ],
  • "product_id": "Stol22",
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "product_name": "Stablestol",
  • "description": "Stablestol for utendørsbruk",
  • "is_virtual_product": false,
  • "unit_gross_price": 10900,
  • "unit": "stk",
  • "currency": "NOK",
  • "starting_at": "2019-08-24T14:15:22Z",
  • "stopping_at": "2019-08-24T14:15:22Z",
  • "dimension": {
    },
  • "images": [],
  • "locations": [
    ],
  • "product_id": "Stol22",
  • "catalog_id": "S23",
  • "catalog_name": "Sommer",
  • "groups": [
    ]
}

Update product

Update an existing product

scopes:

  • admin:products
  • write:products
scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

catalog_id
required
string <= 255 characters

An id that uniquely identifies the catalog. (must not have trailing or leading spaces)

product_id
required
string <= 255 characters

A string that uniquely identifies the product. (must not have trailing or leading spaces)

Request Body schema: application/json
required

products

product_name
string

The products name which is shown to customers

description
string
is_virtual_product
boolean
Default: false
unit_gross_price
integer
unit
string

Unit type

currency
string

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

starting_at
string <date-time>

The product will not be visible until this time

stopping_at
string <date-time>

The product will not be visible after this time

object (Dimension)

Identify item attributes, such as size and color

Array of objects (Images) [ items <= 10 items ]

Links to images of product

Array of objects (Location)

All locations connected to the product

Responses

Request samples

Content type
application/json
{
  • "product_name": "Stablestol",
  • "description": "Stablestol for utendørsbruk",
  • "is_virtual_product": false,
  • "unit_gross_price": 10900,
  • "unit": "stk",
  • "currency": "NOK",
  • "starting_at": "2019-08-24T14:15:22Z",
  • "stopping_at": "2019-08-24T14:15:22Z",
  • "dimension": {
    },
  • "images": [],
  • "locations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "product_name": "Stablestol",
  • "description": "Stablestol for utendørsbruk",
  • "is_virtual_product": false,
  • "unit_gross_price": 10900,
  • "unit": "stk",
  • "currency": "NOK",
  • "starting_at": "2019-08-24T14:15:22Z",
  • "stopping_at": "2019-08-24T14:15:22Z",
  • "dimension": {
    },
  • "images": [],
  • "locations": [
    ],
  • "product_id": "Stol22",
  • "catalog_id": "S23",
  • "catalog_name": "Sommer"
}

Delete product

Delete product in a given catalog

scopes:

  • admin:products
  • write:products
scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

catalog_id
required
string <= 255 characters

An id that uniquely identifies the catalog. (must not have trailing or leading spaces)

product_id
required
string <= 255 characters

A string that uniquely identifies the product. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "product_name": "Stablestol",
  • "description": "Stablestol for utendørsbruk",
  • "is_virtual_product": false,
  • "unit_gross_price": 10900,
  • "unit": "stk",
  • "currency": "NOK",
  • "starting_at": "2019-08-24T14:15:22Z",
  • "stopping_at": "2019-08-24T14:15:22Z",
  • "dimension": {
    },
  • "images": [],
  • "locations": [
    ],
  • "product_id": "Stol22",
  • "catalog_id": "S23",
  • "catalog_name": "Sommer"
}

tax

Taxgroup collection

Lists all taxgroups

scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

Responses

Response samples

Content type
application/json
{
  • "tax_groups": [
    ],
  • "starting_after": "string"
}

Create new taxgroup

Insert a new taxgroup

scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

tax_group

tax_id
string <= 255 characters

The id you have defined for the taxgroup (must not have training or leading spaces). An auto-generated tax_id will be created if not provided

tax_group
string

The taxgroup name which is usually shown

description
string
amount
number
percentage
number
tax_code
string

Responses

Request samples

Content type
application/json
{
  • "tax_group": "Vmva-høy",
  • "description": "Taxgroup for food. Currently 12%",
  • "amount": 10000,
  • "percentage": 12,
  • "tax_code": 3
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "tax_id": "vmva1",
  • "tax_group": "Vmva-høy",
  • "description": "Taxgroup for food. Currently 12%",
  • "amount": 10000,
  • "percentage": 12,
  • "tax_code": 3
}

Update taxgroup

Update an existing taxgroup

scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

tax_id
required
string <= 255 characters

A string that uniquely identifies the tax. (must not have trailing or leading spaces)

Request Body schema: application/json
required

tax_group

tax_group
string

The taxgroup name which is usually shown

description
string
amount
number
percentage
number
tax_code
string

Responses

Request samples

Content type
application/json
{
  • "tax_group": "Vmva-høy",
  • "description": "Taxgroup for food. Currently 12%",
  • "amount": 10000,
  • "percentage": 12,
  • "tax_code": 3
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "tax_id": "vmva1",
  • "tax_group": "Vmva-høy",
  • "description": "Taxgroup for food. Currently 12%",
  • "amount": 10000,
  • "percentage": 12,
  • "tax_code": 3
}

Delete taxgroup

Delete an existing taxgroup

scopes: ["admin:products","write:products"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

tax_id
required
string <= 255 characters

A string that uniquely identifies the tax. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "tax_id": "vmva1",
  • "tax_group": "Vmva-høy",
  • "description": "Taxgroup for food. Currently 12%",
  • "amount": 10000,
  • "percentage": 12,
  • "tax_code": 3
}

receipts

Create new Receipts

Post receipts

scopes:

  • admin:receipts
  • write:receipts
scopes: ["admin:receipts","write:receipts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
token_expire_days
integer >= 1

Generate tokens for the receipts created, the token can be used to retrieve the receipt from:

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.
Request Body schema: application/json
required

receipt

Array
required
object (Store)
receipt_id
required
string non-empty
purchase_at
required
string <date-time>

The date and time for the receipt purchase

Array of objects (DiscountRefs)

List all discounts referenced in discount_lines

Array of objects (ReceiptItem)
object

Details for the delivery

customer_id
string <= 255 characters

The customer id identifying the customer. (must not have trailing or leading spaces)

object

The customer, owner of the receipt

gross_amount
integer

Monetary amount in smallest unit for the currency before discounts

gross_amount_dwh
string

Monetary amount in smallest unit for the currency before discounts with decimal

net_amount
integer

Monetary amount in smallest unit for the currency after discounts

net_amount_dwh
string

Monetary value in smallest unit for the currency after discounts with decimal

round_off_to_coin
integer
currency
string

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

order_number
string
transaction_date
string <date-time>
amount_due
integer

How much more need to be paid before the transaction is completed. Monetary amount in smallest unit for the currency

amount_due_dwh
string

Monetary value with decimal

no_of_items
number

How many items did the customer buy

is_changed
boolean

Discount applied to gross amount

transaction_id
string
total_discount
integer
total_manual_discount_amount
integer

Monetary amount in smallest unit for the currency

total_manual_percentage_discount
integer
operator_id
string

POS user

operator_name
string

Name of the POS user

salesperson_id
string

ID of the POS user

salesperson_name
string
entry_status
string
Enum: "None" "Voided" "Posted" "Concluded" "Cancelled" "OnHold" "Training"

Status for the transaction

comment
string
Array of objects (TaxItem)

Breakdown of the tax to different tax groups

Array of objects (PaymentItem)
Array of objects (InfoCodeItem)
receipt_text
string
discount_code
Array of strings
Array of objects (ExtraInfo)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "receipts": [
    ],
  • "duplicates": 0
}

Update receipt

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
scopes: ["admin:receipts","read:receipts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

receipt_id
required
string

A string that uniquely identifies POS receipt

Request Body schema: application/json
required

changes

customer_id
required
string <= 255 characters

Add customer_id to existing receipt.

The customer id identifying the customer. (must not have trailing or leading spaces)

Array of objects (DiscountRefs)

Add discount to existing receipt.

Responses

Request samples

Content type
application/json
{
  • "customer_id": "C13db4f63",
  • "discounts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "discounts": [
    ],
  • "store": {
    },
  • "items": [
    ],
  • "receipt_id": "714118",
  • "delivery": {
    },
  • "customer_id": "C13db4f63",
  • "customer": {
    },
  • "gross_amount": 59800,
  • "gross_amount_dwh": "59800.01",
  • "net_amount": 47840,
  • "net_amount_dwh": "47840.01",
  • "round_off_to_coin": 100,
  • "currency": "NOK",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "order_number": "order12345",
  • "transaction_date": "2019-08-24T14:15:22Z",
  • "amount_due": 2050,
  • "amount_due_dwh": "2050.10",
  • "no_of_items": 4,
  • "is_changed": true,
  • "transaction_id": "SC999-9991-1828",
  • "total_discount": 0,
  • "total_manual_discount_amount": 0,
  • "total_manual_percentage_discount": 0,
  • "operator_id": "000210",
  • "operator_name": "Ole Anders",
  • "salesperson_id": "000111",
  • "salesperson_name": "Jesper",
  • "entry_status": "None",
  • "comment": "Kunden ønsker mer for info",
  • "tax_lines": [
    ],
  • "payments": [
    ],
  • "infocode_items": [
    ],
  • "receipt_text": "string",
  • "discount_code": [
    ],
  • "extra_info": [
    ]
}

Claim receipt by token

Update customer_id on receipt identified by token. The token will be invalid after the claim.

scopes:

  • admin:receipts
  • write:receipts
  • user:receipts
scopes: ["admin:receipts","write:receipts","user:receipts","public:receipts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
token
required
string

JWT token for receipt

Request Body schema: application/json
required

new customer id

customer_id
required
string

Responses

Request samples

Content type
application/json
{
  • "customer_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "discounts": [
    ],
  • "store": {
    },
  • "items": [
    ],
  • "receipt_id": "714118",
  • "delivery": {
    },
  • "customer_id": "C13db4f63",
  • "customer": {
    },
  • "gross_amount": 59800,
  • "gross_amount_dwh": "59800.01",
  • "net_amount": 47840,
  • "net_amount_dwh": "47840.01",
  • "round_off_to_coin": 100,
  • "currency": "NOK",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "order_number": "order12345",
  • "transaction_date": "2019-08-24T14:15:22Z",
  • "amount_due": 2050,
  • "amount_due_dwh": "2050.10",
  • "no_of_items": 4,
  • "is_changed": true,
  • "transaction_id": "SC999-9991-1828",
  • "total_discount": 0,
  • "total_manual_discount_amount": 0,
  • "total_manual_percentage_discount": 0,
  • "operator_id": "000210",
  • "operator_name": "Ole Anders",
  • "salesperson_id": "000111",
  • "salesperson_name": "Jesper",
  • "entry_status": "None",
  • "comment": "Kunden ønsker mer for info",
  • "tax_lines": [
    ],
  • "payments": [
    ],
  • "infocode_items": [
    ],
  • "receipt_text": "string",
  • "discount_code": [
    ],
  • "extra_info": [
    ]
}

Get receipt by token

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
scopes: ["admin:receipts","read:receipts","user:receipts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
token
required
string

JWT token for receipt

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "discounts": [
    ],
  • "store": {
    },
  • "items": [
    ],
  • "receipt_id": "714118",
  • "delivery": {
    },
  • "customer_id": "C13db4f63",
  • "customer": {
    },
  • "gross_amount": 59800,
  • "gross_amount_dwh": "59800.01",
  • "net_amount": 47840,
  • "net_amount_dwh": "47840.01",
  • "round_off_to_coin": 100,
  • "currency": "NOK",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "order_number": "order12345",
  • "transaction_date": "2019-08-24T14:15:22Z",
  • "amount_due": 2050,
  • "amount_due_dwh": "2050.10",
  • "no_of_items": 4,
  • "is_changed": true,
  • "transaction_id": "SC999-9991-1828",
  • "total_discount": 0,
  • "total_manual_discount_amount": 0,
  • "total_manual_percentage_discount": 0,
  • "operator_id": "000210",
  • "operator_name": "Ole Anders",
  • "salesperson_id": "000111",
  • "salesperson_name": "Jesper",
  • "entry_status": "None",
  • "comment": "Kunden ønsker mer for info",
  • "tax_lines": [
    ],
  • "payments": [
    ],
  • "infocode_items": [
    ],
  • "receipt_text": "string",
  • "discount_code": [
    ],
  • "extra_info": [
    ]
}

Receipt search

Get receipts matching receipt_id (POS id)

scopes:

  • admin:receipts
  • read:receipts
scopes: ["admin:receipts","read:receipts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
receipt_id
required
string

A string that uniquely identifies POS receipt

Responses

Response samples

Content type
application/json
{
  • "receipts": [
    ],
  • "starting_after": "string"
}

customer receipts

Customer Receipts collection

Get the receipts for a customer

scopes:

  • admin:receipts
  • read:receipts
  • user:receipts
scopes: ["admin:receipts","read:receipts","user:receipts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

Responses

Response samples

Content type
application/json
{
  • "receipts": [
    ],
  • "starting_after": "string"
}

Customer receipt details

Get a customer receipt

scopes:

  • admin:receipts
  • read:receipts
  • user:receipts
scopes: ["admin:receipts","read:receipts","user:receipts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

receipt_id
required
string

A string that uniquely identifies POS receipt

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "discounts": [
    ],
  • "store": {
    },
  • "items": [
    ],
  • "receipt_id": "714118",
  • "delivery": {
    },
  • "customer_id": "C13db4f63",
  • "customer": {
    },
  • "gross_amount": 59800,
  • "gross_amount_dwh": "59800.01",
  • "net_amount": 47840,
  • "net_amount_dwh": "47840.01",
  • "round_off_to_coin": 100,
  • "currency": "NOK",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "order_number": "order12345",
  • "transaction_date": "2019-08-24T14:15:22Z",
  • "amount_due": 2050,
  • "amount_due_dwh": "2050.10",
  • "no_of_items": 4,
  • "is_changed": true,
  • "transaction_id": "SC999-9991-1828",
  • "total_discount": 0,
  • "total_manual_discount_amount": 0,
  • "total_manual_percentage_discount": 0,
  • "operator_id": "000210",
  • "operator_name": "Ole Anders",
  • "salesperson_id": "000111",
  • "salesperson_name": "Jesper",
  • "entry_status": "None",
  • "comment": "Kunden ønsker mer for info",
  • "tax_lines": [
    ],
  • "payments": [
    ],
  • "infocode_items": [
    ],
  • "receipt_text": "string",
  • "discount_code": [
    ],
  • "extra_info": [
    ]
}

Change customer_id

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
scopes: ["admin:receipts","read:receipts","user:receipts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

receipt_id
required
string

A string that uniquely identifies POS receipt

Request Body schema: application/json
required

Receipt update

customer_id
string [ 1 .. 255 ] characters

New customer_id (must not have trailing or leading spaces).

Responses

Request samples

Content type
application/json
{
  • "customer_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "discounts": [
    ],
  • "store": {
    },
  • "items": [
    ],
  • "receipt_id": "714118",
  • "delivery": {
    },
  • "customer_id": "C13db4f63",
  • "customer": {
    },
  • "gross_amount": 59800,
  • "gross_amount_dwh": "59800.01",
  • "net_amount": 47840,
  • "net_amount_dwh": "47840.01",
  • "round_off_to_coin": 100,
  • "currency": "NOK",
  • "purchase_at": "2019-08-24T14:15:22Z",
  • "order_number": "order12345",
  • "transaction_date": "2019-08-24T14:15:22Z",
  • "amount_due": 2050,
  • "amount_due_dwh": "2050.10",
  • "no_of_items": 4,
  • "is_changed": true,
  • "transaction_id": "SC999-9991-1828",
  • "total_discount": 0,
  • "total_manual_discount_amount": 0,
  • "total_manual_percentage_discount": 0,
  • "operator_id": "000210",
  • "operator_name": "Ole Anders",
  • "salesperson_id": "000111",
  • "salesperson_name": "Jesper",
  • "entry_status": "None",
  • "comment": "Kunden ønsker mer for info",
  • "tax_lines": [
    ],
  • "payments": [
    ],
  • "infocode_items": [
    ],
  • "receipt_text": "string",
  • "discount_code": [
    ],
  • "extra_info": [
    ]
}

segment

Customer segmentation

Segment customer by receipt data

scopes:

  • admin:receipts
  • read:receipts
scopes: ["admin:receipts","read:receipts"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

segmentation on receipt data

purchase_from
string <date-time>
purchase_to
string <date-time>
store_ids
Array of strings
Array of objects

Responses

Request samples

Content type
application/json
{
  • "purchase_from": "2019-08-24T14:15:22Z",
  • "purchase_to": "2019-08-24T14:15:22Z",
  • "store_ids": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "customers": [
    ]
}

cards

Create a card

Create a new card

scopes:

  • admin:wallets
  • write:wallets
scopes: ["admin:wallets","write:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

card details

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

amount
required
integer >= 0

Monetary amount in smallest unit for the currency

currency
required
string
Enum: "NOK" "SEK" "DKK" "EUR" "USD"

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

customer_id
string <= 255 characters

The customer id you have defined as the owner of the card. (must not have trailing or leading spaces)

name
string

Display name for the card

type
string
Enum: "gift_card" "credit_note"

The type of the card. The value is one of the following:

  • gift_card - a gift card
  • credit_note - a credit note

Defaults to gift_card

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

active_from
string <date-time>

Optional time when the card is activated. No drawdown transaction will be allowed before if set. (fund transaction is allowed)

expires_at
string <date-time>

Optional expiration time for the card. No transaction will be allowed on an expired card

object (PinGenerator)

How the PIN should be generated.

object (TokenGenerator)

Specify how token should be generated

Responses

Request samples

Content type
application/json
{
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "metadata": {
    },
  • "amount": 50000,
  • "currency": "NOK",
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "pin": {
    },
  • "card_token": {
    }
}

Response samples

Content type
application/json
{
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "amount": 50000,
  • "currency": "NOK",
  • "amount_balance": 50000,
  • "amount_available": 50000,
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "pin": {
    },
  • "card_token": {
    }
}

Get cards

Get all cards for an account

scopes:

  • admin:wallets
  • read:wallets
scopes: ["admin:wallets","read:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

search
string

Will try to match the search to either card_id, customer_id or amount

created_at.gte
string <isodate>

Card created after (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

created_at.lte
string <isodate>

Card created before a date (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

type
string
Enum: "gift_card" "credit_note"

Filter cards by type

status
string
Enum: "unused" "partially_used" "used" "expired"

Filter cards by amount and expiry status

expired_at.gte
string <isodate>

Card expires after (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

expired_at.lte
string <isodate>

Card expires before a date (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

amount
integer

Exact card amount

amount.gte
integer

Lower limit for filtering on card amount.

amount.lte
integer

Upper limit for filtering on card amount.

currency
Array of strings

The currency of the card. ?currency=NOK&currency=SEK

customer
string

Filter cards by customer_id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve card by card ID

Get all details about a card

scopes:

  • admin:wallets
  • read:wallets
scopes: ["admin:wallets","read:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "amount": 50000,
  • "currency": "NOK",
  • "amount_balance": 50000,
  • "amount_available": 50000,
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "tokens": [
    ]
}

Create a token for the card

Create a temporary token (also referred as Card Code) for the card, an temporary alias that must be used when when creating a drawdown transaction

The token can be stored in a barcode to allow use of virtuell card in purchase in POS or webstore

scopes:

  • admin:wallets
  • write:wallets
scopes: ["admin:wallets","write:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

Request Body schema: application/json
required

token details

ref_id
required
string

Unique ref ID provided by the client to support safely retrying requests without accidentally performing the same operation twice

All card transaction must have a unique ref ID, but it is not required that the ref ID is globally unique.

expires_in
required
integer >= 1

The lifetime in seconds for the card token. For example, the value "3600" denotes that the token will expire in one hour from the time the response was generated.

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

object

specify the format for to generate

expires_after_transaction
boolean
Default: true

The token can only be used to create one transaction, card lookup by token will be available until token expires by date

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "ref_id": "string",
  • "format": {
    },
  • "expires_after_transaction": true,
  • "expires_in": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "ref_id": "string",
  • "format": {
    },
  • "expires_after_transaction": true,
  • "expires_in": 1,
  • "token": {
    }
}

Retrieve card by Token

Get details about a card, including the current balance and available funds. No details will be returned for expired tokens

scopes:

  • admin:wallets
  • write:wallets
  • write:wallets:/info
scopes: ["admin:wallets","write:wallets","write:wallets:/info"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
token
required
string

temporary token for a Card

pin
string

PIN for the Card

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "pin": "string"
}

Response samples

Content type
application/json
{
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "amount": 50000,
  • "currency": "NOK",
  • "amount_balance": 50000,
  • "amount_available": 50000,
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

customers

List customer cards

Get the cards active for a customer

scopes:

  • admin:wallets
  • read:wallets
  • user:wallets
scopes: ["admin:wallets","read:wallets","user:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get customer card details

Get all details about a customer card

scopes:

  • admin:wallets
  • read:wallets
  • user:wallets
scopes: ["admin:wallets","read:wallets","user:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "tokens": [
    ],
  • "amount_balance": 50000,
  • "amount_available": 50000,
  • "currency": "NOK"
}

transactions

List card transactions

Retrieve a list of Card's Transaction based on card id

scopes:

  • admin:wallets
  • read:wallets
scopes: ["admin:wallets","read:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create transaction

Create a transaction against a Card using token or card_id. If the Transactions is created as pending, the value will be locked until it is either captured or voided. Transaction ID must be used when capturing or voiding a transaction.

Using card_id or creating a fund transaction requires authorization scope admin:wallets or write:wallets

scopes:

  • admin:wallets
  • write:wallets
  • write:wallets:/transactions
scopes: ["admin:wallets","write:wallets","write:wallets:/transactions"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

transaction details

ref_id
required
string

Unique ref ID provided by the client to support safely retrying requests without accidentally performing the same operation twice

All card transaction must have a unique ref ID, but it is not required that the ref ID is globally unique.

amount
required
integer >= 0

Monetary amount in smallest unit for the currency

currency
required
string
Enum: "NOK" "SEK" "DKK" "EUR" "USD"

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

token
string

required if card_id is not set (cannot be combined with card_id)

card_id
string

required if token is not set (cannot be combined with token)

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

type
string
Default: "drawdown"
Enum: "drawdown" "fund"
pending
boolean
Default: false

If true, the transaction will be created as pending, i.e. the value will be locked until it is either captured or voided.

Only supported when creating a drawdown transaction.

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "card_id": "string",
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000,
  • "currency": "NOK",
  • "type": "drawdown",
  • "pending": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000,
  • "currency": "NOK",
  • "type": "drawdown",
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef"
}

Capture pending transaction

Capture a pending Transaction, thereby collection the amount withheld by the pending transaction.

Option to specify an amount that should be captured. Defaults to capture the full transaction. When the amount specified is less than the reserved/pending, the remaining amount will still be reserved/pending and can be captured later.

scopes:

  • admin:wallets
  • write:wallets
  • write:wallets:/transactions
scopes: ["admin:wallets","write:wallets","write:wallets:/transactions"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

transaction_id
required
string <uuid>

An id that uniqely idetifies a transaction

Request Body schema: application/json
required

capture details

ref_id
required
string

Unique ref ID provided by the client to support safely retrying requests without accidentally performing the same operation twice

All card transaction must have a unique ref ID, but it is not required that the ref ID is globally unique.

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

amount
integer >= 0

Monetary amount in smallest unit for the currency

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000,
  • "currency": "NOK",
  • "type": "drawdown",
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef"
}

Void pending transaction

Void a pending Transaction by unlocking the amount withheld by the pending transaction

scopes:

  • admin:wallets
  • write:wallets
  • write:wallets:/transactions
scopes: ["admin:wallets","write:wallets","write:wallets:/transactions"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

transaction_id
required
string <uuid>

An id that uniqely idetifies a transaction

Request Body schema: application/json
required

void details

ref_id
required
string

Unique ref ID provided by the client to support safely retrying requests without accidentally performing the same operation twice

All card transaction must have a unique ref ID, but it is not required that the ref ID is globally unique.

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "ref_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000,
  • "currency": "NOK",
  • "type": "drawdown",
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef"
}

locations

Locations collection

Get all sales locations, the starting_after have to be set to location_id scopes:

  • admin:locations
  • read:locations
scopes: ["admin:locations","read:locations"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

search
string

lookup locations where search term match name, phone_number, email, organization_number and business_name

status
Array of strings

filter locations by status

country
Array of strings

filter locations by country

phone_number
Array of strings

filter locations by phone_number

organization_number
Array of strings

filter locations by organization_number

email
Array of strings

filter locations by email

type
Array of strings

filter locations by type

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new sales location

Create a sales location scopes:

  • admin:locations
  • write:locations
scopes: ["admin:locations","write:locations"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

location to create

location_id
string <= 255 characters

The id you have defined for the sales location. (must not have trailing or leading spaces). An auto-generated location_id will be created if no location_id is provided

name
string

The location's trade name which is shown to its customers (receipt/signs)

timezone
string

The location's timezone (IANA Timezone)

status
string

The location's status

language_code
string

Language code of the localized company info, as defined by BCP 47 (IETF BCP 47, "Tags for Identifying Languages").

currency
string

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

phone_number
string <^\+?[1-9]\d{1,14}$>

A phone number in E.164 number formatting.

chain
string
email
string
mcc
string <iso-18245> [ 4 .. 4 ]

A four-digit Merchant Category Code (MCC) for the store ISO 18245:2003

gln
string

Company Global Location Number

organization_number
string

Company identification number

business_name
string

The location's legal name

franchise
string

The location is part of a franchise.

type
string

The location type (Physical, Mobile)

website_url
string

The location's website

object

Responses

Request samples

Content type
application/json
{
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "location_id": "S01923",
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

Location details

Get single sales location scopes:

  • admin:locations
  • read:locations
scopes: ["admin:locations","read:locations"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

lid
required
string <= 255 characters

location id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "location_id": "S01923",
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

Update Sales location

Update location properties scopes:

  • admin:locations
  • write:locations
scopes: ["admin:locations","write:locations"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

lid
required
string <= 255 characters

location id

Request Body schema: application/json
required

Location update

name
string

The location's trade name which is shown to its customers (receipt/signs)

timezone
string

The location's timezone (IANA Timezone)

status
string

The location's status

language_code
string

Language code of the localized company info, as defined by BCP 47 (IETF BCP 47, "Tags for Identifying Languages").

currency
string

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

phone_number
string <^\+?[1-9]\d{1,14}$>

A phone number in E.164 number formatting.

chain
string
email
string
mcc
string <iso-18245> [ 4 .. 4 ]

A four-digit Merchant Category Code (MCC) for the store ISO 18245:2003

gln
string

Company Global Location Number

organization_number
string

Company identification number

business_name
string

The location's legal name

franchise
string

The location is part of a franchise.

type
string

The location type (Physical, Mobile)

website_url
string

The location's website

object

Responses

Request samples

Content type
application/json
{
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "location_id": "S01923",
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

Delete location

Delete single location scopes:

  • admin:locations
  • write:locations
scopes: ["admin:locations","write:locations"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

lid
required
string <= 255 characters

location id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "location_id": "S01923",
  • "name": "TKP Store",
  • "timezone": "Europe/Oslo",
  • "status": "Active",
  • "language_code": "string",
  • "currency": "NOK",
  • "phone_number": "+4799999999",
  • "chain": "SuperChain",
  • "email": "saleslocation@example.com",
  • "mcc": "5814",
  • "gln": "string",
  • "organization_number": "123456789MVA",
  • "business_name": "TKP technology AS",
  • "franchise": "Subway",
  • "type": "string",
  • "website_url": "string",
  • "address": {
    }
}

subscriptions

Create new subscription

When you create a new webhook, we'll send you a simple ping event to let you know you've set up the webhook correctly. You can trigger a ping again by calling the ping endpoint.

Receiving Webhooks

In order for Dintero to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.

Respond to a webhook

Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range will let Dintero know that you did not receive your webhook, including 301 Redirect. Dintero does not follow redirects for webhook notifications and will consider a redirection as an error response.

Dintero has implemented a 60-second timeout period and a retry period for subscriptions. We wait 120 seconds for a response to each request, and if there isn't one or we get an error, we retry the connection to a total of 5 times. A webhook will be deleted if there are consecutive failures for the exact same webhook. You should monitor the admin of your webhook tool for failing webhooks.

Webhooks Headers

Dintero will send along several HTTP headers to differentiate between event types and payload identifiers.

Name Description
event The event type
event-delivery A guid to indentify the payload and event being sent
event-signature The value of this header is computed as the HMAC SHA1 hex digest of the body, using the secret config option as the key.

scopes:

  • admin:hooks
  • write:hooks
scopes: ["admin:hooks","write:hooks"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

subscription configuration

required
object
events
required
Array of strings[ items non-empty ]
Items Enum: "account_add" "account_update" "receipt_add" "receipt_update" "customer_add" "customer_update" "customer_delete" "customer_change_password" "token_add" "token_remove" "transaction" "wallet_transaction" "discount_add" "discount_update" "discount_delete" "discount_add_customers" "discount_customer_update" "shopping_draft_add" "shopping_draft_update" "shopping_draft_complete" "shopping_order_update" "shopping_order_event_add" "shopping_order_delete" "settlement_add" "location_add" "location_delete" "location_update" "cdd_case_update" "approval_payout_destination_update" "approval_payout_destination_delete" "checkout_transaction"
active
boolean
Default: true

Determines whether the hook is actually triggered.

fields
string <field-mask>

Limit the event data included in the delivery

The syntax is loosely based on XPath:

  • a,b,c comma-separated list will select multiple fields
  • a/b/c path will select a field from its parent
  • a(b,c) sub-selection will select many fields from a parent
  • a/*/c the star * wildcard will select all items in a field

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "config": {
    },
  • "fields": "account(partner_id,account_id,created_at)",
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "active": true,
  • "config": {
    },
  • "fields": "account(partner_id,account_id,created_at)",
  • "events": [
    ]
}

Subscriptions collection

Get all subscriptions

scopes:

  • admin:hooks
  • read:hooks
scopes: ["admin:hooks","read:hooks"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
include_deleted
boolean
Default: false

include deleted subscriptions in the response.

limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

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.

total
boolean
Default: false

include total-count header in the response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Subscription details

Get subscription details

scopes:

  • admin:hooks
  • read:hooks
scopes: ["admin:hooks","read:hooks"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

hid
required
string <uuid>

subscription id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "active": true,
  • "config": {
    },
  • "fields": "account(partner_id,account_id,created_at)",
  • "events": [
    ]
}

Delete Subscription

Delete a webhook subscription

No more events will be sent to the webhook

scopes:

  • admin:hooks
  • write:hooks
scopes: ["admin:hooks","write:hooks"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

hid
required
string <uuid>

subscription id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "active": true,
  • "config": {
    },
  • "fields": "account(partner_id,account_id,created_at)",
  • "events": [
    ]
}

subscription deliveries

Deliveries

Get recent subscription deliveries

scopes:

  • admin:hooks
  • read:hooks
scopes: ["admin:hooks","read:hooks"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

hid
required
string <uuid>

subscription id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delivery details

Get subscription delivery details

scopes:

  • admin:hooks
  • read:hooks
scopes: ["admin:hooks","read:hooks"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

hid
required
string <uuid>

subscription id

delivery_id
required
string

delivery id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "event_delivery": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "status": 200,
  • "url": "string",
  • "request": {
    },
  • "response": {
    },
  • "details": {
    }
}

Subscription ping

This will trigger a ping event to be sent to the subscription URL.

Ping Event Payload

  POST /
    User-Agent: Dintero-Hook/0c9ad03b
    Content-Type: application/json
    event: ping
    event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9

    {
      "created_at": "2017-12-06T15:36:43Z",
      "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
      "id": "string",
      "updated_at": "2017-12-06T15:36:43Z",
      "active": true,
      "config": {
        "content_type": "application/json",
        "insecure_ssl": 0,
        "secret": { ... }
        "url": "string"
      },
      "events": ["receipt_add"]
    }

scopes:

  • admin:hooks
  • write:hooks
scopes: ["admin:hooks","write:hooks"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

hid
required
string <uuid>

subscription id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

log events

Add log event

Endpoint intended for Dintero frontend to report any error raised during operation

Request Body schema: application/json
required
account_id
string
request_id
string

request-id received from Dintero API request

client_session_id
string

frontend session id

Array of objects

Additional metadata about the error event

message
string
error
string

Responses

Request samples

Content type
application/json
{
  • "account_id": "string",
  • "request_id": "string",
  • "client_session_id": "string",
  • "metadata": [],
  • "message": "string",
  • "error": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}