> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/bin-numbers.md).

# Bin Numbers

Administrative endpoints for **bin numbers** — the leading digits of a payment card that identify the bank and the card programme that issued it. Each record binds one set of leading digits to a card definition, so that when a customer starts typing a card number on the storefront the platform can recognise which card it is and offer the installment options, terminals and 3D secure rules configured for that card.

A record is small: the digits themselves, the card they belong to, and whether the record is in use.

### Core Capabilities

**1. Listing & Filtering**

* Retrieve a paginated list of bin numbers, ordered by identifier ascending.
* Filter by identifier, card or the digits themselves. All three filters match the whole value exactly; a partial value returns an empty page.
* Order results with the `sort` parameter, as described under **Filtering & Ordering**.

**2. Lifecycle Management**

* Register a set of leading digits against a card.
* Fully or partially update an existing record.
* Deactivate a record. `DELETE` is a **soft delete** — the record is kept and its digits stay reserved. See **Deleting a Bin Number**.

**3. Uniqueness**

* The digits identify the record and must be unique across all bin numbers, deactivated ones included. A create or update that would repeat digits already stored is rejected.

### Bin Number Fields

| Field               | Type    | Description                                                                                                                                                                                                                        |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pk`                | integer | The unique identifier of the record. Assigned by the server; supplying it in a request body has no effect.                                                                                                                         |
| `bin_number`        | string  | The leading digits of the card. Required on create and on full update, optional on a partial update. Exactly 6 or 8 characters, digits only, and unique across all records. It may not be sent as `null`. See **Accepted Digits**. |
| `card`              | integer | The identifier of the card these digits belong to. Required on create and on full update.                                                                                                                                          |
| `is_active`         | boolean | Whether the record is in use. Defaults to `true` on create. A deactivated record is still returned by the listing and retrieval endpoints.                                                                                         |
| `bin_number_length` | string  | Read-only. The number of characters in `bin_number`, reported as text — `"6"` or `"8"`. Sending it in a request body has no effect.                                                                                                |

### Accepted Digits

A value for `bin_number` is accepted only when it is exactly 6 or 8 characters long and made up entirely of digits. There is a single exception: the placeholder value reserved for Google Pay, which contains letters and is configured per deployment. See **Dynamic Settings & Environment Variables**.

### Deleting a Bin Number

> **Important:** `DELETE` never removes the record. Its active state is set to `false`, and it keeps appearing in the list and can still be retrieved by its identifier.

Two consequences are worth knowing:

* The digits stay reserved. They cannot be registered again on another card while the deactivated record exists — reuse the existing record instead, by setting `is_active` back to `true`.
* Deletion is never refused. Because the record is kept, no other record can block the request the way a still-referenced bank or card would.

### Filtering & Ordering

Bin numbers can be filtered with the `id`, `card`, and `bin_number` query parameters. Each is an **exact** match — `?bin_number=454671` returns the record, while `?bin_number=4546` returns an empty page. Query parameters that are not listed here are ignored rather than rejected. There is no filter for the active state; deactivated records are always included and have to be told apart by their `is_active` value.

Results can be ordered with the `sort` parameter on `pk`, `bin_number`, `card`, and `is_active`. Prefix the field with a hyphen for descending order, and separate several fields with commas. `bin_number_length` is calculated while the response is built rather than stored, so it cannot be used for ordering. When `sort` is omitted, records are returned by identifier ascending.

### Dynamic Settings & Environment Variables

No dynamic settings (`dj_dynamic_settings`) are read by these endpoints. Listing, filtering, creation, update, and deactivation behave identically regardless of how the management panel is configured. The payment module's dynamic settings — such as the 3D Secure and installment settings — govern how payments are processed on the storefront and have no effect on the administrative endpoints in this section.

**Environment variables:** One deployment setting changes what these endpoints accept.

| Variable          | Type   | Default  | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GPAY_BIN_NUMBER` | string | `GPAY00` | The placeholder value that stands in for a card paid through Google Pay, where the real leading digits are never disclosed to the store. It is the only value exempt from the digits-only rule, so it can be stored as a `bin_number` even though it contains letters. The length rule still applies: the value must be 6 or 8 characters long, otherwise it is rejected like any other input. Changing it on a running deployment does not rewrite records already stored. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/bin-numbers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
