CompanyCustomFields

Create or update a custom field of a company

Creates the custom field with this key, or updates it if the company already has one. Repeating the request leaves the same state, so it is safe to run on every deployment to seed a catalogue.

  • Status: 201 when the field is created, 200 when it already existed.
  • Key: it is the path, never the body, and it never changes. To stop using a field, archive it (is_archived: true); fields are never deleted.
  • Archive state: omitting is_archived keeps the current one, so repeating the request never reactivates a field someone archived.
  • Suggestions: omitting suggest_values keeps the current setting; a new field starts with true. Use false for a value that changes on every invoice, such as an order number: invoices store the text as sent and no options are created. Turning it off deletes no option, and turning it back on offers them again.
  • Options: the response carries the common options of the field, or none when suggest_values is false.
put/v1/companies/{company_id}/custom-fields/{key}

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/custom-fields/{key}
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

labelstring required

Name people see next to the value. Leading and trailing spaces are removed; a label that is empty after that answers 422.

show_on_pdfboolean required

Whether the PDF of invoices saved from now on prints this field.

suggest_valuesboolean

true offers the values already used as options and adds new ones as invoices are saved; false stores each value as sent and creates no options. Omit it to keep the current setting; a new field starts with true. Turning it off deletes no option.

is_archivedboolean

true archives the field, false reactivates it. Omit it to keep the current state.

Example request

{
  "label": "Store",
  "show_on_pdf": true
}

Response

The custom field already existed and was updated.

successboolean required

Example response

{
  "success": true,
  "data": {
    "id": "7d2f8a40-3c1e-4b6a-9f0d-2e5b8c1a4d77",
    "key": "store",
    "label": "Store",
    "show_on_pdf": true,
    "suggest_values": true,
    "is_archived": false,
    "options": [
      {
        "id": "0b6c1e2f-5a4d-4c3b-8e7f-1a2b3c4d5e6f",
        "value": "Online store",
        "customer_id": null,
        "is_archived": false
      },
      {
        "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
        "value": "Gran Vía 12",
        "customer_id": "4f244735-980b-4d9c-80e8-6331fa0b1958",
        "is_archived": false
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.