Storebox
API docs by Redocly

Storebox Loyalty Settlement API (1.0.0)

Download OpenAPI specification:Download

Storebox: support@storebox.com URL: https://developer.storebox.com Terms of Service

Introduction

With the Loyalty Settlement platform users can earn points or real money when using thier payment card in a store. By processing payment card transactions or merchant receipts contributions will be calculated as a percentage of the amount on the current transaction.

Calculated contributions is returned by the API as a settlement. Each settlement has a user share and a provider share. The user share is the value that the user has earned and the provider share is the fee to the provider (the consumer of this api). Settlements can be summed up at intervals and the the merchant can be charged.

As a Loyalty Settlement provider partnerships must be made with different merchants with agreement on the percentage for user share and provider share. After agreement the merchant can be created but to start receiveing payment transactions the user must signup thier payment card to Storebox.

This can be done with our Card API if you, as a provider, have the users in your own user/member system. Or if Storebox should do the user administration, then a user should be created through our Loyalty API and afterwards cards can be added to a user.

Merchants

Merchants are the central part of the Loyalty Settlement API. A merchant is the high level resource with relations to companies, stores, categories and campaigns.

Add merchant

Add a single merchant. To start receiving payment transactions then add a Company resource afterwards.

Authorizations:
basicAuth
Request Body schema: application/json
merchantId
string [ 1 .. 32 ] characters

External id of the merchant. Automatically generated upon creation if not provided.

merchantName
required
string [ 1 .. 128 ] characters

Name of the merchant

Responses

Request samples

Content type
application/json
{
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantName": "Test Merchant"
}

Response samples

Content type
application/json
{
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantName": "Test Merchant",
  • "merchantStatus": "active",
  • "companies": [
    ],
  • "campaigns": [
    ]
}

Get merchants

Get all registered merchants.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get merchant

Get a single merchant by merchantId.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
{
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantName": "Test Merchant",
  • "merchantStatus": "active",
  • "companies": [
    ],
  • "campaigns": [
    ],
  • "stores": [
    ],
  • "categories": [
    ],
  • "derivedShares": [
    ]
}

Update merchant

Update one or more fields for a merchant by merchantId. The merchantId cannot be updated.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Request Body schema: application/json
merchantName
string [ 1 .. 128 ] characters

Name of the merchant

merchantStatus
string
Default: "active"
Enum: "active" "disabled"

Status of the merchant

Responses

Request samples

Content type
application/json
{
  • "merchantName": "Test Merchant",
  • "merchantStatus": "active"
}

Delete merchant

Delete a merchant by merchantId.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Get companies

Get companies for a merchant by merchantId.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get stores

Get stores for a merchant by merchantId.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get categories

Get categories for a merchant by merchantId.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get campaigns

Get campaigns for a merchant by merchantId.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get derived shares

Get all derived shares for a merchant by merchantId.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Replace derived shares

Replace all derived shares for a merchant by merchantId.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Request Body schema: application/json
required
Array of objects

The list of derived shares to replace existing derived shares.

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

Get invoices

Get invoices data for a merchant by merchantId.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Settlement Source States

Get the state of each settlement source.

Authorizations:
basicAuth
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Settle merchants

Settle with merchants. Will sum up settlments pr. merchant pr. type (user share and provider share) and create invoice data accordingly. The returned settlementId can be used to fetch invoice data through /api/v1/invoices.

Authorizations:
basicAuth
query Parameters
externalMerchantId
string
Example: externalMerchantId=mdo9afaoaoy2u7tomdy9y1mzcpftvdpk

External id of merchant

Responses

Response samples

Content type
application/json
{
  • "settlementId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3"
}

Settlements

A settlement represents a payment transaction with calculated contribution values to the user and provider.

Get settlements by date

Get settlements by a date range for all or specific merchants.

Authorizations:
basicAuth
query Parameters
startdate
required
string <date-time>
Example: startdate=2018-05-18T08:00:00+02:00

Earliest date/time to search for settlements records in ISO-8601 format. This date represents the settlement system processing datetime. Requires URL encoding.

enddate
required
string <date-time>
Example: enddate=2018-05-18T20:00:00+02:00

Latest date/time to search for settlements records in ISO-8601 format. This date represents the settlement system processing datetime. Requires URL encoding.

merchant
string
Example: merchant=merchant1,merchant2

Comma-separated list with of external merchant id's that should be included in the response. The value _all_ can be provided to get settlements for all merchants.

offset
integer
Default: 0

Return settlements in the given date interval starting at this index.

limit
integer <= 1000
Default: 1000

The number of settlements to return.

Responses

Request samples 

curl -H "Accept: application/json" -H "Content-Type:
application/json" -H "Authorization: Basic {base64 encoded
username:password}"
"https://{host}/api/v1/settlements?startDate=2018-05-
30T08%3A00%3A00%2B02%3A00&endDate=2018-05-
30T20%3A00%3A00%2B02%3A00&merchant=_all_"

Response samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 0,
  • "totalSize": 0,
  • "settlements": [
    ]
}

Get settlements by batchId

Get settlements by batchId. The batchId can be provided by Storebox through a HTTP notification. See Notifications.

Authorizations:
basicAuth
path Parameters
batchId
required
string
Example: mdo9afaoaoy2u7tomdy9y1mzcpftvdpk

External id of the settlement batch.

query Parameters
merchant
string
Example: merchant=merchant1,merchant2

Comma-separated list with of external merchant id's that should be included in the response. The value _all_ can be provided to get settlements for all merchants.

offset
integer
Default: 0

Return settlements in the given date interval starting at this index.

limit
integer <= 1000
Default: 1000

The number of settlements to return.

Responses

Response samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 0,
  • "totalSize": 0,
  • "settlements": [
    ]
}

Create settlement batch

Create a batch of settlements with a reference to all settlements which at the time was not already in a batch.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
{
  • "batchId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3",
  • "settlements": 221,
  • "created": "2019-08-24T14:15:22Z"
}

Get settlement batches

Get all settlement batches.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Companies

A company is created by a company registration number (in danish CVR-nummer) and will enable data flow of payment transactions for that specific registration number. A merchant will receive payment transactions for all created companies. If a company is configured with zero userShare and providerShare then transactions will only be matched if the transaction has a store number (merchantId/cardAcceptorId) which matches a created Store resource.

Add company

Add new company to start receiving payment transactions for the provided company registration number.

Authorizations:
basicAuth
Request Body schema: application/json
companyId
string [ 1 .. 32 ] characters

External id of the company. Automatically generated upon creation if not provided.

merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

name
required
string [ 1 .. 128 ] characters

Name of the company.

companyRegistrationNumber
required
string [ 1 .. 128 ] characters

The company registration number (in Denmark CVR number).

userShare
required
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the user share. Maximum of 2 decimals.

userShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The user share value type.

providerShare
required
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the provider share. Maximum of 2 decimals.

providerShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The provider share value type.

Responses

Request samples

Content type
application/json
{
  • "companyId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Test Company",
  • "companyRegistrationNumber": 12346790,
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage"
}

Response samples

Content type
application/json
{
  • "companyId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Test Company",
  • "companyRegistrationNumber": 12346790,
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage"
}

Get company

Get a single company by companyId.

Authorizations:
basicAuth
path Parameters
companyId
required
string

External id of the company.

Responses

Response samples

Content type
application/json
{
  • "companyId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Test Company",
  • "companyRegistrationNumber": 12346790,
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage"
}

Update company

Update one or more fields on a company. The companyId and merchantId cannot be updated.

Authorizations:
basicAuth
path Parameters
companyId
required
string

External id of the company.

Request Body schema: application/json
name
string [ 1 .. 128 ] characters

Name of the company.

companyRegistrationNumber
string [ 1 .. 128 ] characters

The company registration number (in Denmark CVR number).

userShare
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the user share. Maximum of 2 decimals.

userShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The user share value type.

providerShare
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the provider share. Maximum of 2 decimals.

providerShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The provider share value type.

Responses

Request samples

Content type
application/json
{
  • "name": "Test Company",
  • "companyRegistrationNumber": 12346790,
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage"
}

Delete company

Delete a company by external id of the company.

Authorizations:
basicAuth
path Parameters
companyId
required
string

External id of the company.

Responses

Stores

A store is created by a store number. The store number should match the merchantId/cardAccceptorId on payment agreement with the transaction provider (eg. NETS). The store can be used to differentiate userShare and providerShare values by store number overriding userShare and providerShare from a Company with matching company registration number.

Add store

Add new store providing a storeNumber with seperate userShare and providerShare percentages.

Authorizations:
basicAuth
Request Body schema: application/json
storeId
string [ 1 .. 32 ] characters

External id of the store. Automatically generated upon creation if not provided.

merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

storeNumber
required
string

The number of the store.

name
required
string

The name of the store.

userShare
required
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the user share. Maximum of 2 decimals.

userShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The user share value type.

providerShare
required
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the provider share. Maximum of 2 decimals.

providerShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The provider share value type.

source
string
Default: "transaction"
Enum: "transaction" "receipt"

The source of data to match against the shop.

Responses

Request samples

Content type
application/json
{
  • "storeId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "storeNumber": "39898634",
  • "name": "Test store",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "source": "transaction"
}

Response samples

Content type
application/json
{
  • "storeId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "storeNumber": "39898634",
  • "name": "Test store",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "source": "transaction"
}

Get store

Get a single store by storeId.

Authorizations:
basicAuth
path Parameters
storeId
required
string

External id of the store.

Responses

Response samples

Content type
application/json
{
  • "storeId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "storeNumber": "39898634",
  • "name": "Test store",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "source": "transaction"
}

Update store

Update one or more fields on a store. Empty values will be omitted. The storeId and merchantId cannot be updated.

Authorizations:
basicAuth
path Parameters
storeId
required
string

External id of the store.

Request Body schema: application/json
storeNumber
string

The number of the store.

name
string

The name of the store.

userShare
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the user share. Maximum of 2 decimals.

userShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The user share value type.

providerShare
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the provider share. Maximum of 2 decimals.

providerShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The provider share value type.

source
string
Default: "transaction"
Enum: "transaction" "receipt"

The source of data to match against the shop.

Responses

Request samples

Content type
application/json
{
  • "storeNumber": "39898634",
  • "name": "Test store",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "source": "transaction"
}

Delete store

Delete a store by external id of the store.

Authorizations:
basicAuth
path Parameters
storeId
required
string

External id of the store.

Responses

Product Categories

A product category is used when the merchant is configured to receive receipts. A category will hold a list of products and will be matched if the receipt contains product numbers that match some of the product categories.

Get products

Get products for a category.

Authorizations:
basicAuth
path Parameters
categoryId
required
string

External id of the category.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add products

Will add a list of products to the category.

Authorizations:
basicAuth
path Parameters
categoryId
required
string

External id of the category.

Request Body schema: application/json
Array
productId
string [ 1 .. 32 ] characters

External id of the product. Automatically generated upon creation.

categoryId
string [ 1 .. 32 ] characters

External id of the category which the product belongs to.

name
string <= 128 characters

The name of the product.

productNumber
required
string <= 128 characters

The product number of the product.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "productId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "categoryId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Milk",
  • "productNumber": "1000"
}

Add category

Add new category with seperate userShare and providerShare percentages for a group of products.

Authorizations:
basicAuth
Request Body schema: application/json
categoryId
string [ 1 .. 32 ] characters

External id of the category. Automatically generated upon creation if not provided.

merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

name
required
string

The name of the category.

userShare
required
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the user share. Maximum of 2 decimals.

userShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The user share value type.

providerShare
required
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the provider share. Maximum of 2 decimals.

providerShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The provider share value type.

storeNumber
string

The number of the store if the category is store specific.

Responses

Request samples

Content type
application/json
{
  • "categoryId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Magazines",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "storeNumber": "39898634"
}

Response samples

Content type
application/json
{
  • "categoryId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Magazines",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "storeNumber": "39898634"
}

Get category

Get a single category by categoryId.

Authorizations:
basicAuth
path Parameters
categoryId
required
string

External id of the category.

Responses

Response samples

Content type
application/json
{
  • "categoryId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Magazines",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "storeNumber": "39898634"
}

Update category

Update one or more fields on a category. Empty values will be omitted. The categoryId and merchantId cannot be updated.

Authorizations:
basicAuth
path Parameters
categoryId
required
string

External id of the category.

Request Body schema: application/json
name
string

The name of the category.

userShare
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the user share. Maximum of 2 decimals.

userShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The user share value type.

providerShare
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the provider share. Maximum of 2 decimals.

providerShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The provider share value type.

storeNumber
string

The number of the store if the category is store specific.

Responses

Request samples

Content type
application/json
{
  • "name": "Magazines",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "storeNumber": "39898634"
}

Delete category

Delete a category by campaignId.

Authorizations:
basicAuth
path Parameters
categoryId
required
string

External id of the category.

Responses

Campaigns

Get campaigns

List all campaign either currently active or in the future.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add campaign

Add new campaign for a merchant with seperate userShare and providerShare percentages in a specific period.

Authorizations:
basicAuth
Request Body schema: application/json
campaignId
string [ 1 .. 32 ] characters

External id of the campaign. Automatically generated upon creation if not provided.

merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

name
string <= 64 characters

Name of the campaign.

campaignStart
required
string <date-time>

The start date for the campaign ISO-8601 formatted.

campaignEnd
required
string <date-time>

The end date for the campaign ISO-8601 formatted.

userShare
required
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the user share. Maximum of 2 decimals.

userShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The user share value type.

providerShare
required
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the provider share. Maximum of 2 decimals.

providerShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The provider share value type.

storeNumber
string

The store number for which the campaign should be activated for.

categoryId
string

The external id of the category for which the campaign should be activated for.

productNumber
string

The product number for which the campaign should be activated for.

Responses

Request samples

Content type
application/json
{
  • "campaignId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Soda",
  • "campaignStart": "2018-11-08T17:32:28Z",
  • "campaignEnd": "2018-11-10T17:32:28Z",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "storeNumber": "100",
  • "categoryId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "productNumber": "1000"
}

Response samples

Content type
application/json
{
  • "campaignId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Soda",
  • "campaignStart": "2018-11-08T17:32:28Z",
  • "campaignEnd": "2018-11-10T17:32:28Z",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "storeNumber": "100",
  • "categoryId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "productNumber": "1000"
}

Get campaign

Get a single campaign by campaignId.

Authorizations:
basicAuth
path Parameters
campaignId
required
string

External id of the campaign.

Responses

Response samples

Content type
application/json
{
  • "campaignId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Soda",
  • "campaignStart": "2018-11-08T17:32:28Z",
  • "campaignEnd": "2018-11-10T17:32:28Z",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "storeNumber": "100",
  • "categoryId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "productNumber": "1000"
}

Update campaign

Update one or more fields on a campaign. Empty values will be omitted. The campaignId and merchantId cannot be updated.

Authorizations:
basicAuth
path Parameters
campaignId
required
string

External id of the campaign.

Request Body schema: application/json
name
string <= 64 characters

Name of the campaign.

campaignStart
string <date-time>

The start date for the campaign ISO-8601 formatted.

campaignEnd
string <date-time>

The end date for the campaign ISO-8601 formatted.

userShare
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the user share. Maximum of 2 decimals.

userShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The user share value type.

providerShare
number <double> [ 0 .. 100 ]

The percentage or amount of the transaction amount that will be the provider share. Maximum of 2 decimals.

providerShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount" "derived"

The provider share value type.

storeNumber
string

The store number for which the campaign should be activated for.

categoryId
string

The external id of the category for which the campaign should be activated for.

productNumber
string

The product number for which the campaign should be activated for.

Responses

Request samples

Content type
application/json
{
  • "name": "Soda",
  • "campaignStart": "2018-11-08T17:32:28Z",
  • "campaignEnd": "2018-11-10T17:32:28Z",
  • "userShare": 7.5,
  • "userShareType": "percentage",
  • "providerShare": 2.5,
  • "providerShareType": "percentage",
  • "storeNumber": "100",
  • "categoryId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "productNumber": "1000"
}

Delete campaign

Delete a campaign by campaignId.

Authorizations:
basicAuth
path Parameters
campaignId
required
string

External id of the campaign.

Responses

Derived Shares

A derived share is a share (userShare or providerShare) which is derived from the value of the other share. Example: The providerShare on a Company have providerShareType 'derived'. Then the value from userShare will be used to lookup providerShare in Derived Shares for the current merchant during settlement.

Add derived share

Add derived share to a merchant.

Authorizations:
basicAuth
Request Body schema: application/json
derivedShareId
string <= 32 characters

External id of the derived share. Automatically generated upon creation if not provided.

merchantId
required
string <= 32 characters

External id of the merchant.

share
required
number <double> [ 0 .. 100 ]

The share value which will be used to lookup the derived share value. Max 2 decimals.

derivedShare
required
number <double> [ 0 .. 100 ]

The derived share value. Max 2 decimals.

derivedShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount"

The derived share value type.

Responses

Request samples

Content type
application/json
{
  • "derivedShareId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3",
  • "merchantId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3",
  • "share": 2.5,
  • "derivedShare": 0.5,
  • "derivedShareType": "percentage"
}

Response samples

Content type
application/json
{
  • "derivedShareId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3",
  • "merchantId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3",
  • "share": 2.5,
  • "derivedShare": 0.5,
  • "derivedShareType": "percentage"
}

Get derived share

Get derived share by derived share id.

Authorizations:
basicAuth
path Parameters
derivedShareId
required
any <string>

External id of the derived share.

Responses

Response samples

Content type
application/json
{
  • "derivedShareId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3",
  • "merchantId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3",
  • "share": 2.5,
  • "derivedShare": 0.5,
  • "derivedShareType": "percentage"
}

Update derived share

Update one or more fields on a derived share. Empty values will be omitted.

Authorizations:
basicAuth
path Parameters
derivedShareId
required
any <string>

External id of the derived share.

Request Body schema: application/json
share
number <double> [ 0 .. 100 ]

The share value which will be used to lookup the derived share value. Max 2 decimals.

derivedShare
number <double> [ 0 .. 100 ]

The derived share value. Max 2 decimals.

derivedShareType
string
Default: "percentage"
Enum: "percentage" "fixed_amount"

The derived share value type.

Responses

Request samples

Content type
application/json
{
  • "share": 2.5,
  • "derivedShare": 0.5,
  • "derivedShareType": "percentage"
}

Response samples

Content type
application/json
{
  • "derivedShareId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3",
  • "merchantId": "x4w1amapkiejo1wyb91vq5g1vayr6cx3",
  • "share": 2.5,
  • "derivedShare": 0.5,
  • "derivedShareType": "percentage"
}

Delete derived share

Delete the derived share by id.

Authorizations:
basicAuth
path Parameters
derivedShareId
required
any <string>

External id of the derived share.

Responses

Products

A product is created by a product number (eg. EAN). Which product numbers that can be used have to be agreed with and current store sending the receipt to Storebox.

Add product

Add new product to a specified category.

Authorizations:
basicAuth
Request Body schema: application/json
productId
string [ 1 .. 32 ] characters

External id of the product. Automatically generated upon creation.

categoryId
required
string [ 1 .. 32 ] characters

External id of the category which the product belongs to.

name
string <= 128 characters

The name of the product.

productNumber
required
string <= 128 characters

The product number of the product.

Responses

Request samples

Content type
application/json
{
  • "productId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "categoryId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Milk",
  • "productNumber": "1000"
}

Response samples

Content type
application/json
{
  • "productId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "categoryId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Milk",
  • "productNumber": "1000"
}

Delete product

Delete a product by productId.

Authorizations:
basicAuth
path Parameters
productId
required
string

Responses

Blocked Products

A blocked product is created by product number (eg. EAN) and will ensure acroos merchants that these products will never be matched for settlment.

Get blocked products

Get list of all blocked products

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add blocked product

Add new blocked product which will never be used to calculate settlements.

Authorizations:
basicAuth
Request Body schema: application/json
productId
string [ 1 .. 32 ] characters

External id of the product. Automatically generated upon creation.

name
string <= 128 characters

The name of the product.

productNumber
required
string <= 128 characters

The product number of the product.

Responses

Request samples

Content type
application/json
{
  • "productId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Milk",
  • "productNumber": "1000"
}

Response samples

Content type
application/json
{
  • "productId": "dsff4aoaoy2u7tomdy9y1mzcpftvdpk",
  • "name": "Milk",
  • "productNumber": "1000"
}

Add blocked products

Add a list of blocked products which will never be used to calculate settlements.

Authorizations:
basicAuth
Request Body schema: application/json
Array
productId
string [ 1 .. 32 ] characters

External id of the product. Automatically generated upon creation.

name
string <= 128 characters

The name of the product.

productNumber
required
string <= 128 characters

The product number of the product.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Delete blocked product

Delete a blocked product by productId.

Authorizations:
basicAuth
path Parameters
productId
required
any <string>

Responses

Invoices

An invoice is a sum of merchant settlements by contribution type - a user share sum and a provider share sum.

Get invoices

Get invoice data by settlementId. The settlementId can be provided by Storebox through a HTTP notification. See Notifications.

Authorizations:
basicAuth
path Parameters
settlementId
required
string
Example: tk91q8wcd8690gymm004gn1frplt8io0

The settlement id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Notifications

When certain events happen within the platform, a notification can be dispatched.

In order to setup notications, Storebox must receive an URL per notification type with static authentication headers. Storebox will not append information of the event type to the URL.

Storebox monitors the response code returned, but will not handle the response body.

Note: None of the endpoints, in the "Notifications" section, exists in the Loyalty Settlement API, but are endpoints the integrator must implement and expose. The suggested URL's, are only examples, and you, as an integrator, are free to define your own.

New settlement batch

Notification that will be send when a new settlement batch has been created. The batchId will accessible as a query parameter and can be used to fetch settlements by endpoint /api/settlements/{batchId}

Note: You do not have to use "/new-settlement-batch-notification" in the path, when implementing the receiving endpoint.

Its possible to get all settlements from a batch delivered by JSON file to a SFTP server.

query Parameters
batchId
required
any <string>
Example: batchId=tk91q8wcd8690gymm004gn1frplt8io0

Responses

Merchants settled

Notification that will be send when one or more merchants has been settled. The settlementId will accessible as a query parameter and can be used to fetch invoices by endpoint /api/invoices/{settlementId}

Note: You do not have to use "/new-settle-notification" in the path, when implementing the receiving endpoint.

Its possible to get the invoices delivered by CSV file to a SFTP server.

query Parameters
settlementId
required
any <string>
Example: settlementId=tk91q8wcd8690gymm004gn1frplt8io0

Responses

Transactions

The raw transaction information as delivered from the transaction provider.

Get transactions by batchId

Get transactions by batchId.

Authorizations:
basicAuth
path Parameters
batchId
required
string
Example: mdo9afaoaoy2u7tomdy9y1mzcpftvdpk

External id of the transaction batch.

query Parameters
offset
integer
Default: 0

Return settlements in the given date interval starting at this index.

limit
integer <= 1000
Default: 1000

The number of settlements to return.

Responses

Response samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 0,
  • "totalSize": 0,
  • "results": [
    ]
}

Get transaction batches

Get all tranactions batches.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Changes 2020-05-07

Added Transaction API.

Added endpoint Settlement Source States for resource Merchant.

Added new field for resource Settlement: cardType

Changes 2019-08-06

Added new fields userShareType and providerShareType for resources Company, Store, Category and Campaign. The fields can have values 'percentage', 'fixed_amount' or 'derived'. The default value will be 'percentage'. If 'fixed_amount' then the specificed amount will be equal to the settled amount.

New entity Derived Share added. Can be used to create a mapping table for shares. For example could providerShare be derived by entered userShare by lookup in derived shares. The shareType must be set to 'derived' to activate this behaviour.