Discounts

Operations related to discounts

Get store discounts

get

Retrieves general product discounts for the store. Use the page parameter to paginate results.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: read-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pageintegerOptional

The page number to retrieve.

Default: 1

max_pageintegerOptional

The maximum number of elements per page. This number must be between 5-50.

Default: 50

Responses

200

Successful operation

application/json

discount_countnumberOptionalExample: 12

403

Missing or invalid Tip4Serv API Key

application/json

500

Internal server error

application/json

get/store/discount/discounts

GET /v1/store/discount/discounts HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "discounts": [
    {
      "id": 42,
      "name": "Summer Sale",
      "value": 20,
      "minimum_spending": 50,
      "assign": "all_products_and_subscriptions",
      "recurring": false,
      "start_date": 1758583356,
      "expiration_date": 1761234717,
      "accepted_categories": [
        1,
        3
      ],
      "accepted_products": [
        10,
        25
      ]
    }
  ],
  "discount_count": 12
}

Get a store gift card

get

Get a store gift card by it's code.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: read-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

codestringRequired

The code of the giftcard.

Responses

200

Successful operation

application/json

idinteger · int64Required

Unique identifier of the gift card.

Example: 334

namestringRequired

Name of the gift card.

Example: £50 Gift Card

creation_dateintegerRequired

Timestamp of gift card creation in the store's timezone.

Example: 1758563356951

codestringRequired

Unique code of the gift card.

Example: 0M35-HYBA-IYWT-Y280

initial_creditintegerRequired

Initial credit value of the gift card in its currency.

Example: 50

remaining_creditintegerRequired

Remaining credit on the gift card in its currency.

Example: 43.47

currencystringRequired

Currency of the gift card.

Example: EUR

payment_idinteger · int64Optional

Internal identifier of the payment used to purchase the gift card.

Example: 30689

expirationintegerOptional

Timestamp of gift card expiration in the store's timezone.

Example: 1758563356951

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

404

Gift card not found

application/json

500

Internal server error

application/json

get/store/discount/giftcard/{code}

GET /v1/store/discount/giftcard/{code} HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 334,
  "name": "£50 Gift Card",
  "creation_date": 1758563356951,
  "code": "0M35-HYBA-IYWT-Y280",
  "initial_credit": 50,
  "remaining_credit": 43.47,
  "currency": "EUR",
  "payment_id": 30689,
  "expiration": 1758563356951
}

Delete every useless gift cards.

delete

Delete every useless gift cards. This includes, those which expired by their expiration date, but also those which have a remaining credit of 0.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: delete-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Successful operation

application/json

messagestringOptionalExample: 5 gift cards were successfully deleted.

deleted_giftcardsintegerOptionalExample: 5

statusintegerOptionalExample: 200

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

500

Internal server error

application/json

delete/store/discount/giftcard/useless

DELETE /v1/store/discount/giftcard/useless HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "5 gift cards were successfully deleted.",
  "deleted_giftcards": 5,
  "status": 200
}

Get a store gift card

get

Get a store gift card by it's ID.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: read-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idnumberRequired

The ID of the giftcard.

Responses

200

Successful operation

application/json

idinteger · int64Required

Unique identifier of the gift card.

Example: 334

namestringRequired

Name of the gift card.

Example: £50 Gift Card

creation_dateintegerRequired

Timestamp of gift card creation in the store's timezone.

Example: 1758563356951

codestringRequired

Unique code of the gift card.

Example: 0M35-HYBA-IYWT-Y280

initial_creditintegerRequired

Initial credit value of the gift card in its currency.

Example: 50

remaining_creditintegerRequired

Remaining credit on the gift card in its currency.

Example: 43.47

currencystringRequired

Currency of the gift card.

Example: EUR

payment_idinteger · int64Optional

Internal identifier of the payment used to purchase the gift card.

Example: 30689

expirationintegerOptional

Timestamp of gift card expiration in the store's timezone.

Example: 1758563356951

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

404

Gift card not found

application/json

500

Internal server error

application/json

get/store/discount/giftcard/{id}

GET /v1/store/discount/giftcard/{id} HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 334,
  "name": "£50 Gift Card",
  "creation_date": 1758563356951,
  "code": "0M35-HYBA-IYWT-Y280",
  "initial_credit": 50,
  "remaining_credit": 43.47,
  "currency": "EUR",
  "payment_id": 30689,
  "expiration": 1758563356951
}

Delete a store gift card

delete

Delete a store gift card by it's id.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: delete-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

The id of the giftcard.

Responses

200

Successful operation

application/json

messagestringOptionalExample: The gift card was successfully deleted.

statusintegerOptionalExample: 200

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

404

Gift card not found

application/json

500

Internal server error

application/json

delete/store/discount/giftcard/{id}

DELETE /v1/store/discount/giftcard/{id} HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "The gift card was successfully deleted.",
  "status": 200
}

Update a store gift card

patch

Update a store gift card.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: update-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idnumberRequired

The ID of the giftcard.

Body

namestringOptional

Name of the gift card.

Example: $25 Gift Card

initial_creditintegerOptional

Initial credit value of the gift card in its currency.

Example: 25

remaining_creditintegerOptional

Remaining credit on the gift card in its currency

Example: 25

update_currencybooleanOptional

Indicate if the gift card currency must be modified to the current store currency.

Example: true

expirationintegerOptional

Timestamp of gift card expiration in the store's timezone. (Set this to null, to remove expiration)

Example: 1758563356951

Responses

200

Successful operation

application/json

idinteger · int64Required

Unique identifier of the gift card.

Example: 334

namestringRequired

Name of the gift card.

Example: £50 Gift Card

creation_dateintegerRequired

Timestamp of gift card creation in the store's timezone.

Example: 1758563356951

codestringRequired

Unique code of the gift card.

Example: 0M35-HYBA-IYWT-Y280

initial_creditintegerRequired

Initial credit value of the gift card in its currency.

Example: 50

remaining_creditintegerRequired

Remaining credit on the gift card in its currency.

Example: 43.47

currencystringRequired

Currency of the gift card.

Example: EUR

payment_idinteger · int64Optional

Internal identifier of the payment used to purchase the gift card.

Example: 30689

expirationintegerOptional

Timestamp of gift card expiration in the store's timezone.

Example: 1758563356951

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

404

Gift card not found

application/json

500

Internal server error

application/json

patch/store/discount/giftcard/{id}

PATCH /v1/store/discount/giftcard/{id} HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "name": "$25 Gift Card",
  "initial_credit": 25,
  "remaining_credit": 25,
  "update_currency": true,
  "expiration": 1758563356951
}

{
  "id": 334,
  "name": "£50 Gift Card",
  "creation_date": 1758563356951,
  "code": "0M35-HYBA-IYWT-Y280",
  "initial_credit": 50,
  "remaining_credit": 43.47,
  "currency": "EUR",
  "payment_id": 30689,
  "expiration": 1758563356951
}

Get a store coupon by it's code

get

Update a store coupon.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: read-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

codestringRequired

The code of the coupon.

Responses

200

Successful operation

application/json

idinteger · int64Required

Unique identifier of the coupon.

Example: 800

codestringRequired

Coupon code used by customers.

Example: 8H3LLGQXF9

typestringRequired

Type of discount. Accepted values: percentage, value

Example: percentage

valueintegerRequired

Discount amount (percentage or fixed value depending on type).

Example: 30

usedintegerRequired

Number of times this coupon has been used.

Example: 10

limitintegerOptional

Maximum number of uses allowed for this coupon.

Example: 100

minimumintegerOptional

Minimum purchase amount in the store's currency required to use the coupon.

Example: 9.99

maximumintegerOptional

Maximum purchase amount in the store's currency allowed to use the coupon.

Example: 49.99

expirationintegerOptional

Expiration timestamp of the coupon in store timezone.

Example: 1758583356951

accepted_categoriesinteger[]Required

List of category IDs eligible for the coupon. Empty array means all categories.

Example: [0,2]

accepted_productsinteger[]Required

List of product IDs eligible for the coupon. Empty array means all products.

Example: [1,2]

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

404

Coupon not found

application/json

500

Internal server error

application/json

get/store/discount/coupon/{code}

GET /v1/store/discount/coupon/{code} HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 800,
  "code": "8H3LLGQXF9",
  "type": "percentage",
  "value": 30,
  "used": 10,
  "limit": 100,
  "minimum": 9.99,
  "maximum": 49.99,
  "expiration": 1758583356951,
  "accepted_categories": [
    0,
    2
  ],
  "accepted_products": [
    1,
    2
  ]
}

Get a store coupon by it's ID

get

Update a store coupon.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: read-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idnumberRequired

The ID of the coupon.

Responses

200

Successful operation

application/json

idinteger · int64Required

Unique identifier of the coupon.

Example: 800

codestringRequired

Coupon code used by customers.

Example: 8H3LLGQXF9

typestringRequired

Type of discount. Accepted values: percentage, value

Example: percentage

valueintegerRequired

Discount amount (percentage or fixed value depending on type).

Example: 30

usedintegerRequired

Number of times this coupon has been used.

Example: 10

limitintegerOptional

Maximum number of uses allowed for this coupon.

Example: 100

minimumintegerOptional

Minimum purchase amount in the store's currency required to use the coupon.

Example: 9.99

maximumintegerOptional

Maximum purchase amount in the store's currency allowed to use the coupon.

Example: 49.99

expirationintegerOptional

Expiration timestamp of the coupon in store timezone.

Example: 1758583356951

accepted_categoriesinteger[]Required

List of category IDs eligible for the coupon. Empty array means all categories.

Example: [0,2]

accepted_productsinteger[]Required

List of product IDs eligible for the coupon. Empty array means all products.

Example: [1,2]

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

404

Coupon not found

application/json

500

Internal server error

application/json

get/store/discount/coupon/{id}

GET /v1/store/discount/coupon/{id} HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 800,
  "code": "8H3LLGQXF9",
  "type": "percentage",
  "value": 30,
  "used": 10,
  "limit": 100,
  "minimum": 9.99,
  "maximum": 49.99,
  "expiration": 1758583356951,
  "accepted_categories": [
    0,
    2
  ],
  "accepted_products": [
    1,
    2
  ]
}

Update a store coupon

patch

Update a store coupon.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: update-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idnumberRequired

The ID of the coupon.

Body

codestringOptional

Coupon code used by customers

Example: 7X2ZZABEF8

typestringOptional

Type of discount. Accepted values percentage, value

Example: value

valueintegerOptional

Discount amount (percentage or fixed value depending on type).

Example: 10

limitintegerOptional

Maximum number of uses allowed for this coupon.

Example: 50

minimumintegerOptional

Minimum purchase amount in the store's currency required to use the coupon.

Example: 9.99

maximumintegerOptional

Maximum purchase amount in the store's currency allowed to use the coupon.

Example: 49.99

expirationintegerOptional

Expiration timestamp of the coupon in store timezone. (Set this to null, to remove expiration)

Example: 1758583356951

accepted_categoriesinteger[]Optional

List of category IDs eligible for the coupon. Empty array means all categories. If omitted this property won't be modified.

Example: [1]

accepted_productsinteger[]Optional

List of product IDs eligible for the coupon. Empty array means all products. If omitted this property won't be modified.

Example: [7,8]

Responses

200

Successful operation

application/json

idinteger · int64Required

Unique identifier of the coupon.

Example: 800

codestringRequired

Coupon code used by customers.

Example: 8H3LLGQXF9

typestringRequired

Type of discount. Accepted values: percentage, value

Example: percentage

valueintegerRequired

Discount amount (percentage or fixed value depending on type).

Example: 30

usedintegerRequired

Number of times this coupon has been used.

Example: 10

limitintegerOptional

Maximum number of uses allowed for this coupon.

Example: 100

minimumintegerOptional

Minimum purchase amount in the store's currency required to use the coupon.

Example: 9.99

maximumintegerOptional

Maximum purchase amount in the store's currency allowed to use the coupon.

Example: 49.99

expirationintegerOptional

Expiration timestamp of the coupon in store timezone.

Example: 1758583356951

accepted_categoriesinteger[]Required

List of category IDs eligible for the coupon. Empty array means all categories.

Example: [0,2]

accepted_productsinteger[]Required

List of product IDs eligible for the coupon. Empty array means all products.

Example: [1,2]

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

404

Coupon not found

application/json

500

Internal server error

application/json

patch/store/discount/coupon/{id}

PATCH /v1/store/discount/coupon/{id} HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 168

{
  "code": "7X2ZZABEF8",
  "type": "value",
  "value": 10,
  "limit": 50,
  "minimum": 9.99,
  "maximum": 49.99,
  "expiration": 1758583356951,
  "accepted_categories": [
    1
  ],
  "accepted_products": [
    7,
    8
  ]
}

{
  "id": 800,
  "code": "8H3LLGQXF9",
  "type": "percentage",
  "value": 30,
  "used": 10,
  "limit": 100,
  "minimum": 9.99,
  "maximum": 49.99,
  "expiration": 1758583356951,
  "accepted_categories": [
    0,
    2
  ],
  "accepted_products": [
    1,
    2
  ]
}

Create a store coupon

post

Create a new store coupon.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: create-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

codestringOptional

Coupon code used by customers. (If not defined a random value will be set)

Example: 8H3LLGQXF9

typestringRequired

Type of discount. Accepted values: percentage, value

Example: percentage

valueintegerRequired

Discount amount (percentage or fixed value depending on type).

Example: 30

limitintegerOptional

Maximum number of uses allowed for this coupon.

Example: 100

minimumintegerOptional

Minimum purchase amount in the store's currency required to use the coupon.

Example: 9.99

maximumintegerOptional

Maximum purchase amount in the store's currency allowed to use the coupon.

Example: 49.99

expirationintegerOptional

Expiration timestamp of the coupon in store timezone.

Example: 1758583356951

accepted_categoriesinteger[]Optional

List of category IDs eligible for the coupon. Empty array means all categories. If omitted will accept every category

Example: [0,2]

accepted_productsinteger[]Optional

List of product IDs eligible for the coupon. Empty array means all products. If omitted will accept every product.

Example: [1,2]

Responses

200

Successful operation

application/json

idinteger · int64Required

Unique identifier of the coupon.

Example: 800

codestringRequired

Coupon code used by customers.

Example: 8H3LLGQXF9

typestringRequired

Type of discount. Accepted values: percentage, value

Example: percentage

valueintegerRequired

Discount amount (percentage or fixed value depending on type).

Example: 30

usedintegerRequired

Number of times this coupon has been used.

Example: 10

limitintegerOptional

Maximum number of uses allowed for this coupon.

Example: 100

minimumintegerOptional

Minimum purchase amount in the store's currency required to use the coupon.

Example: 9.99

maximumintegerOptional

Maximum purchase amount in the store's currency allowed to use the coupon.

Example: 49.99

expirationintegerOptional

Expiration timestamp of the coupon in store timezone.

Example: 1758583356951

accepted_categoriesinteger[]Required

List of category IDs eligible for the coupon. Empty array means all categories.

Example: [0,2]

accepted_productsinteger[]Required

List of product IDs eligible for the coupon. Empty array means all products.

Example: [1,2]

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

409

Conflicting conditions

application/json

500

Internal server error

application/json

post/store/discount/coupon

POST /v1/store/discount/coupon HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 176

{
  "code": "8H3LLGQXF9",
  "type": "percentage",
  "value": 30,
  "limit": 100,
  "minimum": 9.99,
  "maximum": 49.99,
  "expiration": 1758583356951,
  "accepted_categories": [
    0,
    2
  ],
  "accepted_products": [
    1,
    2
  ]
}

{
  "id": 800,
  "code": "8H3LLGQXF9",
  "type": "percentage",
  "value": 30,
  "used": 10,
  "limit": 100,
  "minimum": 9.99,
  "maximum": 49.99,
  "expiration": 1758583356951,
  "accepted_categories": [
    0,
    2
  ],
  "accepted_products": [
    1,
    2
  ]
}

Get store coupons

get

Retrieves detailed information about all of your coupons. Use the page parameter to paginate results.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: read-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pageintegerOptional

The page number to retrieve.

Default: 1

max_pageintegerOptional

The maximum number of elements per page. This number must be between 5-50.

Default: 50

Responses

200

Successful operation

application/json

coupon_countnumberOptionalExample: 23

403

Missing or invalid Tip4Serv API Key

application/json

500

Internal server error

application/json

get/store/discount/coupons

GET /v1/store/discount/coupons HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "coupons": [
    {
      "id": 800,
      "code": "8H3LLGQXF9",
      "type": "percentage",
      "value": 30,
      "used": 10,
      "limit": 100,
      "minimum": 9.99,
      "maximum": 49.99,
      "expiration": 1758583356951,
      "accepted_categories": [
        0,
        2
      ],
      "accepted_products": [
        1,
        2
      ]
    }
  ],
  "coupon_count": 23
}

Create store gift card

post

Create store gift card.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: create-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

namestringRequired

Name of the gift card.

Example: £50 Gift Card

initial_creditintegerRequired

Initial credit value of the gift card in its currency.

Example: 50

expirationintegerOptional

Timestamp of gift card expiration in the store's timezone.

Example: 1758563356951

Responses

200

Successful operation

application/json

idinteger · int64Required

Unique identifier of the gift card.

Example: 334

namestringRequired

Name of the gift card.

Example: £50 Gift Card

creation_dateintegerRequired

Timestamp of gift card creation in the store's timezone.

Example: 1758563356951

codestringRequired

Unique code of the gift card.

Example: 0M35-HYBA-IYWT-Y280

initial_creditintegerRequired

Initial credit value of the gift card in its currency.

Example: 50

remaining_creditintegerRequired

Remaining credit on the gift card in its currency.

Example: 43.47

currencystringRequired

Currency of the gift card.

Example: EUR

payment_idinteger · int64Optional

Internal identifier of the payment used to purchase the gift card.

Example: 30689

expirationintegerOptional

Timestamp of gift card expiration in the store's timezone.

Example: 1758563356951

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

500

Internal server error

application/json

post/store/discount/giftcard

POST /v1/store/discount/giftcard HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "name": "£50 Gift Card",
  "initial_credit": 50,
  "expiration": 1758563356951
}

{
  "id": 334,
  "name": "£50 Gift Card",
  "creation_date": 1758563356951,
  "code": "0M35-HYBA-IYWT-Y280",
  "initial_credit": 50,
  "remaining_credit": 43.47,
  "currency": "EUR",
  "payment_id": 30689,
  "expiration": 1758563356951
}

Get store gift cards

get

Retrieves detailed information about all of your gift cards. Use the page parameter to paginate results.

Authorization:

• Requires a valid JWT Bearer token.

• The token must include the permission: read-discounts.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pageintegerOptional

The page number to retrieve.

Default: 1

max_pageintegerOptional

The maximum number of elements per page. This number must be between 5-50.

Default: 50

Responses

200

Successful operation

application/json

giftcard_countnumberOptionalExample: 44

400

Error in your request

application/json

403

Missing or invalid Tip4Serv API Key

application/json

500

Internal server error

application/json

get/store/discount/giftcards

GET /v1/store/discount/giftcards HTTP/1.1
Host: api.tip4serv.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "giftcards": [
    {
      "id": 334,
      "name": "£50 Gift Card",
      "creation_date": 1758563356951,
      "code": "0M35-HYBA-IYWT-Y280",
      "initial_credit": 50,
      "remaining_credit": 43.47,
      "currency": "EUR",
      "payment_id": 30689,
      "expiration": 1758563356951
    }
  ],
  "giftcard_count": 44
}