Forbidden Codes - 1.0.0

API Endpoints

Forbidden Codes
- Description: Use this service call to get forbidden coupon codes for FMTC Merchants.
- Example Request: https://s3.fmtc.co/api/1.0.0/forbidden-codes?api_token=API_KEY

Forbidden Codes API

The Forbidden Codes endpoint contains a collection of restricted coupon codes for FMTC Merchants that are not to be used. In order to receive codes for an FMTC Merchant, you will need to have been approved by the Merchant. This information can be used, in combination with our Deals and Merchants endpoints, to ensure forbidden coupon codes are not used within your own internal system.

Request Parameters

Name	Value	Description	Required	Default
api_token	APIKEY	API key for authentication, available on the API Keys & Calls page.(https://account.fmtc.co/cp/api_keys)	Yes	N/A, must always be provided
format	String XML, JSON, CSV, TAB, or PIPE	Choose the feed format you would like returned.	No	JSON
merchant_ids	Number(s) Comma-separated list of FMTC Merchant IDs. Example: ‘&merchant_ids=1234,12345,123456’	Return only forbidden codes for the particular merchant(s). If you do not specify a merchant_ids value, you will be returned forbidden codes for all merchants you have been approved for.	No	NULL
sort_by	String merchant, added, update	Field to order the results by. ‘merchant’ - order by merchant_id in ascending order. ‘added’ - order by created_at in descending order. ‘update’ - order by updated_at in descending order.	No	merchant
page_size	Number 1 - 1000	Size of each page for the results of this call.	No	100

Implementation

Response Elements

Name	Description
merchant_id	The ID assigned to the merchant by FMTC.
code	The coupon code listed as forbidden for the merchant.
created_at	The date the forbidden code was added to FMTC's database. NOTE: These times will be in UTC time.
updated_at	When this forbidden code was last modified by FMTC. NOTE: These times will be in UTC time.
links - JSON and XML link - CSV, Tab, Pipe - will be located in the HTML link header.	All the different links that are for going through the pagination. first - The first page of the endpoint call. last - The last page of the endpoint call. prev - The previous page of the endpoint call. next - The next page of the endpoint call.
meta	The information about the current endpoint call.

Example Response - JSON

Here is an example of a JSON Response from the Forbidden Codes endpoint.

JSON

{
  "data": [
    {
      "merchant_id": 76913,
      "code": "SHOP3",
      "created_at": "2025-03-18T13:23:14.000000Z",
      "updated_at": "2025-03-18T13:23:14.000000Z"
    },
    {
      "merchant_id": 76947,
      "code": "EWJG",
      "created_at": "2025-03-14T15:32:02.000000Z",
      "updated_at": "2025-03-14T15:32:02.000000Z"
    },
    {
      "merchant_id": 76950,
      "code": "DEAL1",
      "created_at": "2025-03-14T15:32:02.000000Z",
      "updated_at": "2025-03-14T15:32:02.000000Z"
    },
    {
      "merchant_id": 76950,
      "code": "DEAL2",
      "created_at": "2025-03-18T13:23:14.000000Z",
      "updated_at": "2025-03-18T13:23:14.000000Z"
    },
    {
      "merchant_id": 126335,
      "code": "et",
      "created_at": "2025-03-14T16:33:15.000000Z",
      "updated_at": "2025-03-14T16:33:15.000000Z"
    }
  ],
  "links": {
    "first": URL + "&page=1",
    "last": URL + "&page=3",
    "prev": null,
    "next": URL + "&page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 5,
    "last_page": 3,
    "path": "https://s3.fmtc.co/api/1.0.0/forbidden-codes",
    "per_page": 5,
    "total": 14,
    "version": "1.0.0"
  }
}

Example Response - XML

Here is an example of an XML Response from the Forbidden Codes endpoint.

XML

<results>
  <data>
    <forbidden-code>
      <merchant_id>76913</merchant_id>
      <code>SHOP3</code>
      <created_at>2025-03-18 13:23:14</created_at>
      <updated_at>2025-03-18 13:23:14</updated_at>
    </forbidden-code>
    <forbidden-code>
      <merchant_id>76947</merchant_id>
      <code>EWJG</code>
      <created_at>2025-03-14 15:32:02</created_at>
      <updated_at>2025-03-14 15:32:02</updated_at>
    </forbidden-code>
    <forbidden-code>
      <merchant_id>76950</merchant_id>
      <code>DEAL1</code>
      <created_at>2025-03-14 15:32:02</created_at>
      <updated_at>2025-03-14 15:32:02</updated_at>
    </forbidden-code>
    <forbidden-code>
      <merchant_id>76950</merchant_id>
      <code>DEAL2</code>
      <created_at>2025-03-18 13:23:14</created_at>
      <updated_at>2025-03-18 13:23:14</updated_at>
    </forbidden-code>
    <forbidden-code>
      <merchant_id>126335</merchant_id>
      <code>et</code>
      <created_at>2025-03-14 16:33:15</created_at>
      <updated_at>2025-03-14 16:33:15</updated_at>
    </forbidden-code>
  </data>
  <links>
    <first>URL + &page=1</first>
    <last>URL + &page=3</last>
    <prev/>
    <next>URL + &page=2</next>
  </links>
  <meta>
    <current_page>1</current_page>
    <from>1</from>
    <to>5</to>
    <last_page>3</last_page>
    <path>https://s3.fmtc.co/api/1.0.0/forbidden-codes</path>
    <per_page>5</per_page>
    <total>14</total>
    <version>1.0.0</version>
  </meta>
</results>

Example Response - CSV

Here is an example of a CSV Response from the Forbidden Codes endpoint.

CODE

merchant_id,code,created_at,updated_at
76950,DEAL1,"2025-03-14 15:32:02","2025-03-14 15:32:02"
76950,DEAL2,"2025-03-18 13:23:14","2025-03-18 13:23:14"

Example Response - TAB

Here is an example of a TAB Response from the Forbidden Codes endpoint.

CODE

merchant_id	code	created_at	updated_at
76950	DEAL1	"2025-03-14 15:32:02"	"2025-03-14 15:32:02"
76950	DEAL2	"2025-03-18 13:23:14"	"2025-03-18 13:23:14"

Example Response - PIPE

Here is an example of a PIPE Response from the Forbidden Codes endpoint.

CODE

merchant_id|code|created_at|updated_at
76950|DEAL1|"2025-03-14 15:32:02"|"2025-03-14 15:32:02"
76950|DEAL2|"2025-03-18 13:23:14"|"2025-03-18 13:23:14"

Example Error Response

JSON

Example:

JSON

{
  "errors": {
    "merchant_ids.0": [
      "All merchant_ids must be integers."
    ]
  }
}

XML

Example:

CODE

<response>
  <errors>
    <merchant_ids.0>
      <merchant_ids.0>All merchant_ids must be integers.</merchant_ids.0>
    </merchant_ids.0>
  </errors>
</response>

CSV

If you have an error with your API request in CSV, you will receive a JSON Error Response.

TAB

If you have an error with your API request in TAB, you will receive a JSON Error Response.

PIPE

If you have an error with your API request in PIPE, you will receive a JSON Error Response.

Error Responses

Parameter Key	Error String	Description
merchant_ids	All merchant_ids must be integers	All `merchant_ids` must be integers. Please double check the `merchant_ids` parameter and ensure ID is a valid integer or a comma-separated list of valid integers.
format	The requested format is invalid or not supported	The `format` parameter string is either not valid or not supported. Please double check the provided `format` request parameter is valid and supported by the API endpoint.
page_size	The page size field must be an integer.	The page_size passed in must be a numeric integer that consists only of numbers.