> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-sequential-id.md).
# Emporix Sequential ID
Use the emporix-sequential-id skill to define number formats and generate sequential document IDs during implementation.
Use the **emporix-sequential-id** skill to set up and troubleshoot Emporix document numbering. It guides you through creating a sequence schema, activating it, and generating IDs.
{% hint style="info" %}
This page explains when to use the skill and how to work with it. For field constraints, endpoints, and OpenAPI details, see the [Sequential ID Service](/api-documentation/api-guides/utilities/sequential-id/sequentialid.md) guide and the [Sequential IDs management](/api-documentation/api-guides/utilities/sequential-id/api-reference/sequential-ids-management.md) API reference.
{% endhint %}
## Skill details
| Property | Value |
| ------------ | --------------------------------------------------------------- |
| Skill name | `emporix-sequential-id` |
| Package path | `skills/community/emporix-sequential-id/` (contains `SKILL.md`) |
Install it once using [Installing skills](/agentic-commerce-intelligence/agentic-engineering/skill-library.md#installing-skills).
## When to use it
Use this skill when you need to:
* Define or change formats for order, invoice, quote, or customer numbers
* Create or activate a sequence schema (platform or custom `schemaType`)
* Generate a single `nextId` or a batch of IDs
* Run separate number ranges per vendor, period, or channel (`sequenceKey`)
* Resolve placeholders such as `__year__` or `__country__` (including via `siteCode`)
* Diagnose Sequential ID errors (missing active schema, missing placeholders, max value exceeded, unexpected gaps, or legacy endpoint `404`s)
{% hint style="info" %}
For access tokens and `401`/`403` problems, use the [Emporix Auth](/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-auth.md) skill, not this skill alone.
{% endhint %}
## How it works
The Sequential ID Service turns a **sequence schema**, the pattern and counter rules for a number format, into unique, incrementing document numbers. Emporix services always use the active schema for each `schemaType`. To change a format, create a new schema and activate it. Activation replaces the previously active schema for that type. There is no update endpoint for an existing schema.
With the skill installed, you drive that flow in natural language:
```mermaid
---
config:
layout: fixed
theme: base
look: classic
themeVariables:
background: transparent
lineColor: "#9CBBE3"
arrowheadColor: "#9CBBE3"
edgeLabelBackground: "#FFC128"
edgeLabelTextColor: "#4C5359"
---
flowchart LR
A["Confirm tenant
and scopes"]
B["Choose schemaType"]
C["Create schema"]
D["Activate schema"]
E["Generate IDs"]
A --> B --> C --> D --> E
style A fill:#A1BDDC,stroke:#4C5359
style B fill:#DDE6EE,stroke:#4C5359
style C fill:#F2F6FA,stroke:#4C5359
style D fill:#9CBBE3,stroke:#4C5359
style E fill:#FFC128,stroke:#4C5359
A@{ shape: rounded}
B@{ shape: rounded}
C@{ shape: rounded}
D@{ shape: rounded}
E@{ shape: rounded}
```
Use a platform `schemaType` such as `orderNoSequence`, or a custom type for your own integrations. When you need independent counters (pools), pass `sequenceKey` on generate. Endpoint paths are in the Sequential ID Service documentation linked above.
## Prerequisites
Before you use this skill, make sure you have:
* An API key with the `sequentialid.schema_view` scope for viewing and generating IDs, and the `sequentialid.schema_manage` scope for schema management
* A service access token for `https://api.emporix.io`
* A known `siteCode` for site-based date or country placeholder resolution (optional)
## How to use it
After install, work in your AI tool with natural-language requests. Examples:
> Create and activate an order number schema `ORD-__year__-` with 6 digits starting after 1000.
> Generate the next invoice number for site `main`.
> Set up a separate sequence pool per vendor with `sequenceKey`.
> Why do I get `Active schema with the type … doesn't exist` after deleting a schema?
Provide your tenant name. For create or activate calls, confirm the token includes `sequentialid.schema_manage`.
## Usage notes
* First number – Generation returns `startValue + 1`, not `startValue`.
* Unexpected responses – A `400` or `409` can still advance the counter, so expect gaps. Fix the request before retrying in a loop.
* Scopes – `sequentialid.schema_manage` does not include `sequentialid.schema_view`. For generate-only integrations, the `sequentialid.schema_view` scope is usually enough.
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.emporix.io/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-sequential-id.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.