Offers

Server

Download schema

List offers

GET

https://api.wocart.store

/api/offers

X-API-Key (header)

Get all Buy X Get Y promotional offers ordered by creation date (newest first).

List offers › Responses

200

List of offers

success

boolean · required

Offer[] · required

count

integer · required

Number of items returned

GET/api/offers

curl https://api.wocart.store/api/offers \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "off_abc123",
      "name": "اشتري 2 واحصل على 1 مجاناً",
      "triggerProduct": {
        "id": "id",
        "name": "Samsung Galaxy A54",
        "handle": "samsung-galaxy-a54"
      },
      "triggerVariant": {
        "id": "id",
        "label": "أزرق / 128 GB"
      },
      "triggerQuantity": 2,
      "rewardProduct": {
        "id": "id",
        "name": "Samsung Galaxy Buds",
        "handle": "samsung-galaxy-buds"
      },
      "rewardVariant": {
        "id": "id",
        "label": "أبيض"
      },
      "rewardQuantity": 1,
      "discountType": "free",
      "startsAt": null,
      "endsAt": null,
      "status": "active",
      "state": "live",
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ],
  "count": 0
}

json

application/json

Create offer

POST

https://api.wocart.store

/api/offers

X-API-Key (header)

Create a new Buy X Get Y promotional offer.

Auto-application rules (applied at order time, not here):

When a store order is submitted via POST /store/orders, the server checks for any active offer where triggerProductId matches, the ordered quantity ≥ triggerQuantity, and — if triggerVariantId is set — the ordered variantId also matches.
If the reward item is out of stock, the offer is silently skipped (order still succeeds).
The reward is inserted as a $0 order line item; the COD total only reflects paid products + delivery.

Create offer › Request Body

name

string · minLength: 2 · maxLength: 200 · required

triggerProductId

string · minLength: 1 · required

discountType

string · enum

Enum values:

free

free_shipping

quantity_price

Default: free

triggerVariantId

string | null · minLength: 1

triggerQuantity

integer · min: 1 · max: 1000

rewardProductId

string | null · minLength: 1

rewardVariantId

string | null · minLength: 1

rewardQuantity

integer · min: 0 · max: 1000

object[] · maxItems: 10

startsAt

string | null · date-time

endsAt

string | null · date-time

status

string · enum

Enum values:

active

inactive

Default: active

Create offer › Responses

Offer created

success

boolean · required

Offer · required

POST/api/offers

curl https://api.wocart.store/api/offers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "name": "name",
  "discountType": "free",
  "triggerProductId": "triggerProductId",
  "triggerVariantId": "triggerVariantId",
  "triggerQuantity": 1,
  "rewardProductId": "rewardProductId",
  "rewardVariantId": "rewardVariantId",
  "rewardQuantity": 0,
  "tiers": [
    {
      "quantity": 1,
      "price": 0,
      "freeShipping": false
    }
  ],
  "startsAt": "2024-08-25T15:00:00Z",
  "endsAt": "2024-08-25T15:00:00Z",
  "status": "active"
}'

Example Request Body

{
  "name": "name",
  "discountType": "free",
  "triggerProductId": "triggerProductId",
  "triggerVariantId": "triggerVariantId",
  "triggerQuantity": 1,
  "rewardProductId": "rewardProductId",
  "rewardVariantId": "rewardVariantId",
  "rewardQuantity": 0,
  "tiers": [
    {
      "quantity": 1,
      "price": 0,
      "freeShipping": false
    }
  ],
  "startsAt": "2024-08-25T15:00:00Z",
  "endsAt": "2024-08-25T15:00:00Z",
  "status": "active"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "off_abc123",
    "name": "اشتري 2 واحصل على 1 مجاناً",
    "triggerProduct": {
      "id": "id",
      "name": "Samsung Galaxy A54",
      "handle": "samsung-galaxy-a54"
    },
    "triggerVariant": {
      "id": "id",
      "label": "أزرق / 128 GB"
    },
    "triggerQuantity": 2,
    "rewardProduct": {
      "id": "id",
      "name": "Samsung Galaxy Buds",
      "handle": "samsung-galaxy-buds"
    },
    "rewardVariant": {
      "id": "id",
      "label": "أبيض"
    },
    "rewardQuantity": 1,
    "discountType": "free",
    "startsAt": null,
    "endsAt": null,
    "status": "active",
    "state": "live",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Get offer

GET

https://api.wocart.store

/api/offers/{id}

X-API-Key (header)

Get a single offer by ID with fully resolved product and variant references.

Get offer › path Parameters

id

string · required

Offer UUID

Get offer › Responses

200

Offer details

success

boolean · required

Offer · required

GET/api/offers/{id}

curl https://api.wocart.store/api/offers/:id \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": {
    "id": "off_abc123",
    "name": "اشتري 2 واحصل على 1 مجاناً",
    "triggerProduct": {
      "id": "id",
      "name": "Samsung Galaxy A54",
      "handle": "samsung-galaxy-a54"
    },
    "triggerVariant": {
      "id": "id",
      "label": "أزرق / 128 GB"
    },
    "triggerQuantity": 2,
    "rewardProduct": {
      "id": "id",
      "name": "Samsung Galaxy Buds",
      "handle": "samsung-galaxy-buds"
    },
    "rewardVariant": {
      "id": "id",
      "label": "أبيض"
    },
    "rewardQuantity": 1,
    "discountType": "free",
    "startsAt": null,
    "endsAt": null,
    "status": "active",
    "state": "live",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Update offer

PATCH

https://api.wocart.store

/api/offers/{id}

X-API-Key (header)

Partially update an offer. All fields are optional — send only the fields you want to change.

Update offer › path Parameters

id

string · required

Offer UUID

Update offer › Request Body

name

string · minLength: 2 · maxLength: 200

discountType

string · enum

Enum values:

free

free_shipping

quantity_price

triggerProductId

string · minLength: 1

triggerVariantId

string | null · minLength: 1

triggerQuantity

integer · min: 1 · max: 1000

rewardProductId

string | null · minLength: 1

rewardVariantId

string | null · minLength: 1

rewardQuantity

integer · min: 0 · max: 1000

object[] · maxItems: 10

startsAt

string | null · date-time

endsAt

string | null · date-time

status

string · enum

Enum values:

active

inactive

Update offer › Responses

200

Updated offer

success

boolean · required

Offer · required

PATCH/api/offers/{id}

curl https://api.wocart.store/api/offers/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "name": "name",
  "discountType": "free",
  "triggerProductId": "triggerProductId",
  "triggerVariantId": "triggerVariantId",
  "triggerQuantity": 1,
  "rewardProductId": "rewardProductId",
  "rewardVariantId": "rewardVariantId",
  "rewardQuantity": 0,
  "tiers": [
    {
      "quantity": 1,
      "price": 0,
      "freeShipping": false
    }
  ],
  "startsAt": "2024-08-25T15:00:00Z",
  "endsAt": "2024-08-25T15:00:00Z",
  "status": "active"
}'

Example Request Body

{
  "name": "name",
  "discountType": "free",
  "triggerProductId": "triggerProductId",
  "triggerVariantId": "triggerVariantId",
  "triggerQuantity": 1,
  "rewardProductId": "rewardProductId",
  "rewardVariantId": "rewardVariantId",
  "rewardQuantity": 0,
  "tiers": [
    {
      "quantity": 1,
      "price": 0,
      "freeShipping": false
    }
  ],
  "startsAt": "2024-08-25T15:00:00Z",
  "endsAt": "2024-08-25T15:00:00Z",
  "status": "active"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "off_abc123",
    "name": "اشتري 2 واحصل على 1 مجاناً",
    "triggerProduct": {
      "id": "id",
      "name": "Samsung Galaxy A54",
      "handle": "samsung-galaxy-a54"
    },
    "triggerVariant": {
      "id": "id",
      "label": "أزرق / 128 GB"
    },
    "triggerQuantity": 2,
    "rewardProduct": {
      "id": "id",
      "name": "Samsung Galaxy Buds",
      "handle": "samsung-galaxy-buds"
    },
    "rewardVariant": {
      "id": "id",
      "label": "أبيض"
    },
    "rewardQuantity": 1,
    "discountType": "free",
    "startsAt": null,
    "endsAt": null,
    "status": "active",
    "state": "live",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Delete offer

DELETE

https://api.wocart.store

/api/offers/{id}

X-API-Key (header)

Permanently delete an offer. Already-placed orders are not affected.

Delete offer › path Parameters

id

string · required

Offer UUID

Delete offer › Responses

200

Offer deleted

success

boolean · required

Get a offer's translations

GET

https://api.wocart.store

/api/offers/{id}/translations

X-API-Key (header)

The translatable fields in the store's primary language and every stored translation, each flagged outdated when its source text changed after it was written.

Get a offer's translations › path Parameters

id

string · required

Get a offer's translations › Responses

200

Source and translations

success

boolean · required

object · required

GET/api/offers/{id}/translations

curl https://api.wocart.store/api/offers/:id/translations \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": {
    "resource": "resource",
    "id": "id",
    "sourceLocale": "ar",
    "targetLocales": [
      {
        "locale": "ar",
        "published": true
      }
    ],
    "source": {
      "key": "string"
    },
    "options": [
      {
        "name": "name",
        "key": "key",
        "values": [
          {
            "value": "value",
            "key": "key"
          }
        ]
      }
    ],
    "translations": {
      "ar": {
        "key": {
          "value": "value",
          "outdated": true
        }
      },
      "fr": {
        "key": {
          "value": "value",
          "outdated": true
        }
      },
      "en": {
        "key": {
          "value": "value",
          "outdated": true
        }
      }
    }
  }
}

json

application/json

Translate a offer into one language

PATCH

https://api.wocart.store

/api/offers/{id}/translations

X-API-Key (header)

A JSON Merge Patch (RFC 7396) of one language: a string sets a field, null removes its translation, other fields are untouched. The language must be one the store has added, and not its primary — the resource's own fields hold that.

Translate a offer into one language › path Parameters

id

string · required

Translate a offer into one language › Request Body

locale

string · enum · required

Enum values:

object · required

Translate a offer into one language › Responses

200

Source and translations after the patch

success

boolean · required

object · required

PATCH/api/offers/{id}/translations

curl https://api.wocart.store/api/offers/:id/translations \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "locale": "ar",
  "values": {
    "name": "name"
  }
}'

Example Request Body

{
  "locale": "ar",
  "values": {
    "name": "name"
  }
}

json

Example Responses

{
  "success": true,
  "data": {
    "resource": "resource",
    "id": "id",
    "sourceLocale": "ar",
    "targetLocales": [
      {
        "locale": "ar",
        "published": true
      }
    ],
    "source": {
      "key": "string"
    },
    "options": [
      {
        "name": "name",
        "key": "key",
        "values": [
          {
            "value": "value",
            "key": "key"
          }
        ]
      }
    ],
    "translations": {
      "ar": {
        "key": {
          "value": "value",
          "outdated": true
        }
      },
      "fr": {
        "key": {
          "value": "value",
          "outdated": true
        }
      },
      "en": {
        "key": {
          "value": "value",
          "outdated": true
        }
      }
    }
  }
}

json

application/json

Stock Coupons