Coupons

Coupons allows to apply different types of discounts to Invoices, Orders and Plans. Redeemed Coupons will be applied only to Invoices with the same currency.

Retrieve a list of coupon redemptions

Request

Security:

SecretApiKey or JWT

query Parameters

limit	integer [ 0 .. 1000 ] The collection items limit.
offset	integer >= 0 The collection items offset.
filter	string The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.
q	string The partial search of the text fields.
sort	Array of strings The collection items sort field and order (prefix with "-" for descending sort).

header Parameters

Organization-Id

string (ResourceId) <= 50 characters

Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

200

Coupons redemptions were retrieved successfully.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

get/coupons-redemptions

Request samples

$couponRedemptions = $client->couponsRedemptions()->search([
    'filter' => 'customerId:testCustomer',
]);

Response samples

application/json

[{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"additionalRestrictions": [{"type": "discounts-per-redemption"
}
],
"createdTime": "2019-08-24T14:15:22Z",
"canceledTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}
]

Redeem a coupon

Redeem a coupon.

Request

Security:

SecretApiKey or JWT

header Parameters

Organization-Id

string (ResourceId) <= 50 characters

Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Request Body schema: application/json

Redeem a coupon.

couponId

string <= 50 characters

Coupon's ID.

customerId

string <= 50 characters

Customer's ID.

Array of objects (RedemptionRestriction)

Additional restrictions for coupon's redemptions.

Array

type required	string Coupon's restriction type. discounts-per-redemption restrict-to-countries discounts-per-redemption minimum-order-amount redemptions-per-customer restrict-to-invoices restrict-to-plans restrict-to-subscriptions restrict-to-products total-redemptions paid-by-time
quantity required	integer Restriction quantity.

Responses

201

Coupon was redeemed.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

422

Invalid data was sent.

post/coupons-redemptions

Request samples

application/json

{"couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"additionalRestrictions": [{"type": "discounts-per-redemption"
}
]
}

Response samples

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"additionalRestrictions": [{"type": "discounts-per-redemption"
}
],
"createdTime": "2019-08-24T14:15:22Z",
"canceledTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}

Retrieve a coupon redemption with specified identifier string

Request

Security:

SecretApiKey or JWT

path Parameters

required

string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters

Organization-Id

string (ResourceId) <= 50 characters

Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

200

Retrieve a coupon redemption with specified identifier string.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

404

Resource was not found.

get/coupons-redemptions/{id}

Request samples

$couponRedemption = $client->couponsRedemptions()->load('redemptionId');

Response samples

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"additionalRestrictions": [{"type": "discounts-per-redemption"
}
],
"createdTime": "2019-08-24T14:15:22Z",
"canceledTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}

Cancel a coupon redemption

Request

Security:

SecretApiKey or JWT

path Parameters

required

string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters

Organization-Id

string (ResourceId) <= 50 characters

Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

201

Cancel a coupon redemption.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

404

Resource was not found.

post/coupons-redemptions/{id}/cancel

Request samples

$client->couponsRedemptions()->cancel('id');

Response samples

application/json

{"type": "http://example.com",
"status": 400,
"title": "string",
"detail": "string",
"error": "string"
}

Retrieve a list of coupons

Retrieve a list of coupons.

Request

Security:

SecretApiKey or JWT

query Parameters

limit	integer [ 0 .. 1000 ] The collection items limit.
offset	integer >= 0 The collection items offset.
filter	string The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.
q	string The partial search of the text fields.
sort	Array of strings The collection items sort field and order (prefix with "-" for descending sort).

header Parameters

Organization-Id

string (ResourceId) <= 50 characters

Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

200

A list of coupons was retrieved successfully.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

get/coupons

Request samples

$coupons = $client->coupons()->search([
    'filter' => 'status:issued',
]);

Response samples

application/json

[{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"redemptionsCount": 0,
"status": "draft",
"description": "string",
"issuedTime": "2019-08-24T14:15:22Z",
"expiredTime": "2019-08-24T14:15:22Z",
"createdTime": "2019-08-24T14:15:22Z",
"updatedTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}
]

Create a coupon

Create a coupon.

Request

Security:

SecretApiKey or JWT

header Parameters

Organization-Id

string (ResourceId) <= 50 characters

Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Request Body schema: application/json

Coupon resource.

required

object (Discount)

type

string

Discount type.

context

string (DiscountContext)

Default: "items"

The context in which the discount applies.

Enum:	Description
items	items (less discounts)
shipping	shipping (less discounts)
items-and-shipping	items and shipping (less discounts)

amount

required

number <double> > 0

Discount amount.

currency

required

string 3 characters

ISO 4217 alphabetic currency code.

Array of objects (CouponRestriction)

Coupon restrictions.

Array

type required	string Coupon's restriction type. discounts-per-redemption restrict-to-countries discounts-per-redemption minimum-order-amount redemptions-per-customer restrict-to-invoices restrict-to-plans restrict-to-subscriptions restrict-to-products total-redemptions paid-by-time
quantity required	integer Restriction quantity.

description

string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

issuedTime

required

string <date-time>

Coupon's issued time (start time).

expiredTime

string <date-time>

Coupon's expire time (end time).

Responses

201

Coupon was created.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

422

Invalid data was sent.

post/coupons

Request samples

application/json

{"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"description": "string",
"issuedTime": "2019-08-24T14:15:22Z",
"expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"redemptionsCount": 0,
"status": "draft",
"description": "string",
"issuedTime": "2019-08-24T14:15:22Z",
"expiredTime": "2019-08-24T14:15:22Z",
"createdTime": "2019-08-24T14:15:22Z",
"updatedTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}

Retrieve a coupon

Retrieve a coupon with specified coupon ID string.

Request

Security:

SecretApiKey or JWT

path Parameters

required

string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters

Organization-Id

string (ResourceId) <= 50 characters

Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

200

Coupon was retrieved successfully.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

404

Resource was not found.

get/coupons/{id}

Request samples

$coupon = $client->coupons()->load('couponId');

Response samples

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"redemptionsCount": 0,
"status": "draft",
"description": "string",
"issuedTime": "2019-08-24T14:15:22Z",
"expiredTime": "2019-08-24T14:15:22Z",
"createdTime": "2019-08-24T14:15:22Z",
"updatedTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}

Create or update a coupon with predefined coupon ID

Create or update a coupon with predefined coupon ID.

Request

Security:

SecretApiKey or JWT

path Parameters

required

string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters

Organization-Id

string (ResourceId) <= 50 characters

Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Request Body schema: application/json

Coupon resource.

required

object (Discount)

type

string

Discount type.

context

string (DiscountContext)

Default: "items"

The context in which the discount applies.

Enum:	Description
items	items (less discounts)
shipping	shipping (less discounts)
items-and-shipping	items and shipping (less discounts)

amount

required

number <double> > 0

Discount amount.

currency

required

string 3 characters

ISO 4217 alphabetic currency code.

Array of objects (CouponRestriction)

Coupon restrictions.

Array

type required	string Coupon's restriction type. discounts-per-redemption restrict-to-countries discounts-per-redemption minimum-order-amount redemptions-per-customer restrict-to-invoices restrict-to-plans restrict-to-subscriptions restrict-to-products total-redemptions paid-by-time
quantity required	integer Restriction quantity.

description

string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

issuedTime

required

string <date-time>

Coupon's issued time (start time).

expiredTime

string <date-time>

Coupon's expire time (end time).

Responses

200

Coupon was updated.

201

Coupon was created.

401

Unauthorized access, invalid credentials was used.

404

Resource was not found.

409

Conflict.

422

Invalid data was sent.

put/coupons/{id}

Request samples

application/json

{"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"description": "string",
"issuedTime": "2019-08-24T14:15:22Z",
"expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"redemptionsCount": 0,
"status": "draft",
"description": "string",
"issuedTime": "2019-08-24T14:15:22Z",
"expiredTime": "2019-08-24T14:15:22Z",
"createdTime": "2019-08-24T14:15:22Z",
"updatedTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}

Set a coupon's expiration time

Set a coupon's expiry time with the specified coupon ID. The expiredTime of a coupon must be greater than its issuedTime. This cannot be performed on expired coupons.

Request

Security:

SecretApiKey or JWT

path Parameters

required

string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters

Organization-Id

string (ResourceId) <= 50 characters

Deprecated

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Request Body schema: application/json

Coupon resource.

expiredTime

required

string <date-time>

The coupon's expiry time, must be greater than the issued time. Null or empty string will immediately expire the coupon.

Responses

201

Coupon expiration was successfully set.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

404

Resource was not found.

409

The coupon is already expired and has been redeemed, unable to. reschedule expiration.

422

Invalid data was sent.

post/coupons/{id}/expiration

Request samples

application/json

{"expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"redemptionsCount": 0,
"status": "draft",
"description": "string",
"issuedTime": "2019-08-24T14:15:22Z",
"expiredTime": "2019-08-24T14:15:22Z",
"createdTime": "2019-08-24T14:15:22Z",
"updatedTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}

➔ Next to Shipping Rates