Find Order Discount by Code

Beta

POST/v1/sales/order-discounts/actions/find-by-code

Idempotent with Idempotency-Key header. Learn more

Validates a discount code and returns the matching order discount, so a code a buyer typed can be attached to an order.

When buyer_account_id is provided, or the caller is a customer user, the lookup also verifies that the buyer has not already redeemed the discount on another order, and reports an already-redeemed code as not found. Pass sales_order_id to exclude an order the buyer is currently editing from that check.

Permissions requiredValues:discounts:read

The role behind your API key or agent must grant every one of these permissions.

codestring

The discount code to look up, as the buyer typed it.

Matching ignores letter case, so save10 finds a discount stored as SAVE10.

buyer_account_idoptional string

The buyer account to check for prior use of this code.

When set, the lookup returns a not-found error if that buyer has already redeemed the discount on another order, so a one-use-per-customer code can be rejected before it is attached to a new one. Customer callers cannot set this — their own account is always used.

sales_order_idoptional string

Sales order ID to exclude from the prior-usage check.

Set this when re-validating a code on an existing order so the order's own usage does not count against the buyer.

idstring

Order discount ID.

objectstringenumValues:order_discount

Resource type identifier.

namestring

Display name of the discount.

codestring

The code a buyer enters to apply this discount to an order.

Codes are unique within your account and are matched without regard to letter case.

percentagestring (decimal)

The fraction of the order total taken off, as a decimal string.

This is a multiplier, not a whole percent: 0.1 takes 10% off. Only read when discount_type is percentage.

amountstring (decimal)

The flat amount taken off the order total, as a decimal string.

Only read when discount_type is amount.

discount_typestringenumValues:percentageamount

How the discount is calculated.

percentage: the order total is reduced by the fraction in percentage.
amount: the order total is reduced by the flat amount in amount.

order_countinteger

How many sales orders this discount has been applied to, across all buyers.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Responses

200

Successful response for Find Order Discount by Code

Find Order Discount by Code

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const orderDiscount = await client.sales.orderDiscounts.actions.findByCode({ code: 'SAVE10' });

console.log(orderDiscount.id);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const orderDiscount = await client.sales.orderDiscounts.actions.findByCode({ code: 'SAVE10' });

console.log(orderDiscount.id);

200 example

{
  "id": "ords_qnbrjvq5ih2q",
  "object": "order_discount",
  "name": "10% Off",
  "code": "SAVE10",
  "percentage": "10.000000000000000000000000000000",
  "amount": "0.000000000000000000000000000000",
  "discount_type": "percentage",
  "order_count": 5,
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

{
  "id": "ords_qnbrjvq5ih2q",
  "object": "order_discount",
  "name": "10% Off",
  "code": "SAVE10",
  "percentage": "10.000000000000000000000000000000",
  "amount": "0.000000000000000000000000000000",
  "discount_type": "percentage",
  "order_count": 5,
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

Find Order Discount by Code

Authorization

Request Body

Returns

Responses