Create a disabled discount

curl --request POST \
  --url https://api.mercemur.com/api/v1/discounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "code": "<string>",
  "percentage_basis_points": 2,
  "amount_minor": 2,
  "currency_code": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "usage_limit": 2
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: '<string>',
    percentage_basis_points: 2,
    amount_minor: 2,
    currency_code: '<string>',
    starts_at: '2023-11-07T05:31:56Z',
    ends_at: '2023-11-07T05:31:56Z',
    usage_limit: 2
  })
};

fetch('https://api.mercemur.com/api/v1/discounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/discounts"

payload = {
    "code": "<string>",
    "percentage_basis_points": 2,
    "amount_minor": 2,
    "currency_code": "<string>",
    "starts_at": "2023-11-07T05:31:56Z",
    "ends_at": "2023-11-07T05:31:56Z",
    "usage_limit": 2
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercemur.com/api/v1/discounts"

	payload := strings.NewReader("{\n  \"code\": \"<string>\",\n  \"percentage_basis_points\": 2,\n  \"amount_minor\": 2,\n  \"currency_code\": \"<string>\",\n  \"starts_at\": \"2023-11-07T05:31:56Z\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"usage_limit\": 2\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mercemur.com/api/v1/discounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'code' => '<string>',
    'percentage_basis_points' => 2,
    'amount_minor' => 2,
    'currency_code' => '<string>',
    'starts_at' => '2023-11-07T05:31:56Z',
    'ends_at' => '2023-11-07T05:31:56Z',
    'usage_limit' => 2
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "amount_minor": 123,
    "code": "<string>",
    "created_at": "<string>",
    "currency_code": "<string>",
    "ends_at": null,
    "id": "<string>",
    "percentage_basis_points": 123,
    "starts_at": null,
    "status": "<string>",
    "type": "<string>",
    "updated_at": "<string>",
    "usage_limit": 123,
    "used_count": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

POST

api

discounts

Create a disabled discount

curl --request POST \
  --url https://api.mercemur.com/api/v1/discounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "code": "<string>",
  "percentage_basis_points": 2,
  "amount_minor": 2,
  "currency_code": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "usage_limit": 2
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: '<string>',
    percentage_basis_points: 2,
    amount_minor: 2,
    currency_code: '<string>',
    starts_at: '2023-11-07T05:31:56Z',
    ends_at: '2023-11-07T05:31:56Z',
    usage_limit: 2
  })
};

fetch('https://api.mercemur.com/api/v1/discounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/discounts"

payload = {
    "code": "<string>",
    "percentage_basis_points": 2,
    "amount_minor": 2,
    "currency_code": "<string>",
    "starts_at": "2023-11-07T05:31:56Z",
    "ends_at": "2023-11-07T05:31:56Z",
    "usage_limit": 2
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercemur.com/api/v1/discounts"

	payload := strings.NewReader("{\n  \"code\": \"<string>\",\n  \"percentage_basis_points\": 2,\n  \"amount_minor\": 2,\n  \"currency_code\": \"<string>\",\n  \"starts_at\": \"2023-11-07T05:31:56Z\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"usage_limit\": 2\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mercemur.com/api/v1/discounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'code' => '<string>',
    'percentage_basis_points' => 2,
    'amount_minor' => 2,
    'currency_code' => '<string>',
    'starts_at' => '2023-11-07T05:31:56Z',
    'ends_at' => '2023-11-07T05:31:56Z',
    'usage_limit' => 2
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "amount_minor": 123,
    "code": "<string>",
    "created_at": "<string>",
    "currency_code": "<string>",
    "ends_at": null,
    "id": "<string>",
    "percentage_basis_points": 123,
    "starts_at": null,
    "status": "<string>",
    "type": "<string>",
    "updated_at": "<string>",
    "usage_limit": 123,
    "used_count": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.

Headers

Idempotency-Key

string

required

A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.

Body

application/json

Send exactly one of percentage_basis_points or amount_minor. The discount is created DISABLED: a live money rule in front of shoppers must not be a side effect of one call, so going live is a second, idempotent POST /discounts/{discountId}/enable. A retry outside the idempotency window collides on the unique (store, code) index and answers 409 code_taken rather than creating a duplicate.

code

string

required

Required on create. The natural key a shopper types, and what makes a retry outside the idempotency window a 409 code_taken rather than a second discount. UPPER-CASED AND TRIMMED SERVER-SIDE, so "apitest-disc-001" is stored and returned as "APITEST-DISC-001": read the code back from the response rather than assuming the bytes you sent, and note that two codes differing only in case are the SAME code and the second is a 409.

percentage_basis_points

integer

Sets a percentage discount. Basis points, so 15% is 1500 and no rounding question arises. 1..10000. Mutually exclusive with amount_minor.

Required range: x >= 1

amount_minor

integer

Sets a fixed discount, in minor units of the store's base currency. Mutually exclusive with percentage_basis_points, and requires currency_code in the same object.

Required range: x >= 1

currency_code

string

Required with amount_minor and refused without it. An assertion rather than a choice: promotion has no currency column, so this must equal the store's base currency or the write is refused with 409 currency_mismatch.

starts_at

string<date-time>

ends_at

string<date-time>

usage_limit

integer

Total redemptions allowed. Omit, or send null on a patch, for unlimited. Zero is refused rather than read as unlimited.

Required range: x >= 1

Response

Created

data

object

Show child attributes

Overview

Endpoints

Create a disabled discount

Authorizations

Headers

Body

Response