The Atlassian Marketplace REST API

Promotions

Get promotions paged

GET /marketplace/catalog/partners/{partnerId}/promotions/paged

Get a list of promotions for the specified partner in paginated way. This resource requires authentication.

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

Query parameters

limit

integer

Number of result in the response (only for Server and Data Center)

Default: 10, Minimum: 1, Maximum: 1500, Format: int64

offset

integer

If specified, skips ahead by this number of items (only for Server and Data Center)

Default: 0, Format: int64

order-by

anything

If specified, sorts the promotions based on the supplied order by parameter. Uses descending order by default.

Default: CREATION_DATE

active-only

boolean

If specified, returns active promotions only

Default: false

hosting-type

anything

If specified, filters promotions based on the supplied hosting type parameter

app-key

string

If specified, filters promotions based on the supplied app key

ascending

boolean

If specified, sorts promotion in ascending order

Default: false

nextId

string

To navigate in the forward direction, provide the next page Id (only for cloud Promotions)

prevId

string

To navigate in the backward direction, provide the previous page Id (only for cloud Promotions)

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions/paged' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200

401

403

404

502

Content type	Value
application/json	PromotionListPaginatedResponse

Get promotions

GET /marketplace/catalog/partners/{partnerId}/promotions

Get a list of promotions for the specified partner.

This resource requires authentication.

It is strongly recommended to use paginated API. Refer Get promotions paged

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200

401

403

404

502

Content type	Value
application/json	PromotionListResponse

Create promotion

POST /marketplace/catalog/partners/{partnerId}/promotions

Create a new promotion for the specified partner. This resource requires authentication.

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

Body parameters

name Required

string

Name of the promotion

eligibleApps Required

Array<string>

App keys of the apps for which this promotion is applicable

startDate

string

Starting date of the promotion

Format: date

expirationDate Required

string

Expiration date of the promotion

Format: date

promotionType Required

string

Indicates whether this is a shared or single-use promotion

Valid values: SHARED_PROMOTION, SINGLE_USE_PROMOTION

discountType Required

string

Indicates whether the promotion uses flat discount or tiered discount

Valid values: FLAT_DISCOUNT

discountPercent

integer

Discount percentage if this promotion is based on a percentage discount

Format: int32

maxUses

integer

Maximum number of times this promotion can be used if it is a shared promotion

Format: int32

hostingType Required

string

Hosting environment of the apps for which this promotion is applicable.

Valid values: SERVER, DATA_CENTER, CLOUD

subscriptionType

string

Used for cloud promotions to specify type of subscription.

Valid values: MONTHLY, ANNUAL

allowedBillingCycles

integer

Number of billing cycles the promotions is valid for. Used for cloud promotions.

Format: int32

allowUnlimitedUses

boolean

True if the promotions is valid for unlimited uses.

customPromoCode

string

Custom Promo code will be prefixed with an autogenerated string for a shared promotion. In case of any issue with the provided custom promo code, a random promocode will be generated. (Only for Cloud Promotions)

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "eligibleApps": [
    "<string>"
  ],
  "startDate": "<string>",
  "expirationDate": "<string>",
  "promotionType": "SHARED_PROMOTION",
  "discountType": "FLAT_DISCOUNT",
  "discountPercent": 71,
  "maxUses": 78,
  "hostingType": "SERVER",
  "subscriptionType": "MONTHLY",
  "allowedBillingCycles": 80,
  "allowUnlimitedUses": true,
  "customPromoCode": "<string>"
}'

Responses

200

400

401

403

404

409

502

Successfully created

Content type	Value
application/json	CreatePromotionResponse

Get promotion

GET /marketplace/catalog/partners/{partnerId}/promotions/{promotionId}

Get a specific promotion for the specified partner. This resource requires authentication.

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

promotionId Required

string

The unique identifier for this promotion. (UUID for Cloud promotions and string for Server/DC promotions)

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions/{promotionId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200

401

403

404

502

Content type	Value
application/json	PromotionResponse

Update promotion

PATCH /marketplace/catalog/partners/{partnerId}/promotions/{promotionId}

Update a specific promotion for the specified partner. This resource requires authentication.

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

promotionId Required

string

The unique identifier for this promotion. (UUID for Cloud promotions and string for Server/DC promotions)

Body parameters

name

string

Name of the promotion

startDate

string

Starting date of the promotion

Format: date

expirationDate

string

Expiration date of the promotion

Format: date

discountPercent

integer

Discount percentage if this promotion is based on a percentage discount

Format: int32

maxUses

integer

Maximum number of times this promotion can be used if it is a shared promotion

Format: int32

allowedBillingCycles

integer

Number of billing cycles the promotions is valid for. Used for cloud promotions.

Format: int32

Example

cURL

Node.js

Java

Python

PHP

curl --request PATCH \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions/{promotionId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "startDate": "<string>",
  "expirationDate": "<string>",
  "discountPercent": 71,
  "maxUses": 78,
  "allowedBillingCycles": 80
}'

Responses

200

400

401

403

404

409

502

Successfully modified

A schema has not been defined for this response code.

Get promotion codes

GET /marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/codes

Get a list of single-use codes for the specified promotion.

This resource requires authentication.

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

promotionId Required

string

The unique identifier for this promotion. (UUID for Cloud promotions and string for Server/DC promotions)

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/codes' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200

401

403

404

502

Content type	Value
application/json	PromotionCodesResponse

Create promotion code

POST /marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/codes

Create a new single-use code for the specified promotion.

This resource requires authentication.

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

promotionId Required

string

The unique identifier for this promotion. (UUID for Cloud promotions and string for Server/DC promotions)

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request POST \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/codes' \
  --user 'email@example.com:<api_token>'

Responses

200

400

401

403

404

409

502

Successfully created

A schema has not been defined for this response code.

Get promotion code

GET /marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/codes/{promotionCode}

Get a specific single-use code for the specified promotion.

This resource requires authentication.

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

promotionId Required

string

The unique identifier for this promotion. (UUID for Cloud promotions and string for Server/DC promotions)

promotionCode Required

integer

The unique identifier for this promotion code

Format: int32

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/codes/{promotionCode}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200

401

403

404

502

Content type	Value
application/json	PromotionCodeResponse

Delete promotion code

DELETE /marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/codes/{promotionCode}

Delete a specific single-use code for a specific promotion associated with a specific partner.

This resource requires authentication.

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

promotionId Required

string

The unique identifier for this promotion. (UUID for Cloud promotions and string for Server/DC promotions)

promotionCode Required

integer

The unique identifier for this promotion code

Format: int32

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/codes/{promotionCode}' \
  --user 'email@example.com:<api_token>'

Responses

200

400

401

403

404

409

502

Successfully deleted

A schema has not been defined for this response code.

Get promotion status

GET /marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/status

Get a specific promotion status for the specified partner. This resource requires authentication.

Request

Path parameters

partnerId Required

integer

The unique identifier for this partner

Format: int64

promotionId Required

string

The unique identifier for this promotion. (UUID for Cloud promotions and string for Server/DC promotions)

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/marketplace/catalog/partners/{partnerId}/promotions/{promotionId}/status' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200

401

403

404

502

Content type	Value	Restrictions
application/json	string	Valid values: `ACTIVE`, `ENDED_EARLY`, `EXPIRED`