> 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-terraform.md).
# Emporix Terraform
Use the emporix-terraform skill to manage Emporix tenant configuration as code with the official Terraform provider.
Use the **emporix-terraform** skill to manage Emporix tenant configuration with the official `emporix/emporix` Terraform provider. It covers sites, currencies, countries, tax, shipping, payment modes, webhooks, mixin schemas, and tenant-configuration keys.
{% hint style="info" %}
This page explains when to use the skill and how to work with it. The provider manages configuration, not commerce data. For Client ID, Secret, and scopes, use the [Emporix Auth](/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-auth.md) skill.
{% endhint %}
## Skill details
| Property | Value |
| ------------ | ------------------------------------------------- |
| Skill name | `emporix-terraform` |
| Package path | `skills/emporix-terraform/` (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:
* Write Terraform for Emporix tenant setup
* Configure the provider with `EMPORIX_CLIENT_ID`, `EMPORIX_CLIENT_SECRET`, and `EMPORIX_SCOPE`
* Choose the resource that manages a given setting, or use the raw Configuration Service escape hatch
* Promote the same configuration across dev, staging, and production as code
* Diagnose `Error: Invalid JSON` on a `value`, a state break after a provider upgrade, or a 403 from a provider call
## How it works
The provider is a configuration provider. It does not manage products, prices, orders, customers, stock, media, or API keys.
Decide the surface before you write HCL. Indexing and unit handling are examples of config keys the provider does not model yet.
```mermaid
---
config:
layout: fixed
theme: base
look: classic
themeVariables:
background: transparent
lineColor: "#9CBBE3"
arrowheadColor: "#9CBBE3"
edgeLabelBackground: "#FFC128"
edgeLabelTextColor: "#4C5359"
---
flowchart TD
Start["What are you managing?"]
Commerce{"Commerce data
or API keys?"}
Modelled{"Provider models
this setting?"}
Outside["Outside this provider"]
Resource["Provider resource"]
Raw["Raw Configuration Service"]
Start --> Commerce
Commerce -->|Yes| Outside
Commerce -->|No| Modelled
Modelled -->|Yes| Resource
Modelled -->|No| Raw
style Start fill:#F2F6FA,stroke:#4C5359,color:#4C5359
style Commerce fill:#DDE6EE,stroke:#4C5359,color:#4C5359
style Modelled fill:#DDE6EE,stroke:#4C5359,color:#4C5359
style Outside fill:#A1BDDC,stroke:#4C5359,color:#4C5359
style Resource fill:#A1BDDC,stroke:#4C5359,color:#4C5359
style Raw fill:#A1BDDC,stroke:#4C5359,color:#4C5359
Start@{ shape: rounded}
Outside@{ shape: rounded}
Resource@{ shape: rounded}
Raw@{ shape: rounded}
```
The provider is pre-1.0. Pin an exact version. A minor upgrade can require a state change. Run `terraform plan` and `terraform apply` on a sandbox tenant first.
Credentials are environment variables. An empty provider block plus exported `EMPORIX_*` variables keeps secrets out of the repository and out of state.
## Prerequisites
Before you use this skill, make sure you have:
* Terraform 1.0 or newer
* A sandbox tenant – do not apply against production
* `EMPORIX_TENANT` and either `EMPORIX_CLIENT_ID` plus `EMPORIX_CLIENT_SECRET`, or a pre-minted `EMPORIX_ACCESS_TOKEN`
* A custom API key limited to the manage and read scopes of the resources you manage
## How to use it
After install, work in your AI tool from the Terraform directory. Examples:
> Add the `emporix/emporix` provider, pin the version, and configure it from environment variables.
> Manage site `store-de` and the EUR currency as Terraform resources on my sandbox tenant.
> Why does `emporix_tenant_configuration` fail with `Error: Invalid JSON` when `value` is a plain string?
## Usage notes
* `value` must be JSON. Wrap plain strings with `jsonencode`.
* The API returns the decoded value. Terraform state keeps the encoded form. A mismatch on read-back is the encoding, not a failed write.
* Raw config writes need a `Content-Language` header. Omitting it returns 400, "The Content-Language cannot be empty".
* `emporix_country` updates the pre-populated country. It does not create or delete countries, and it does not manage regions.
* The provider has no data sources. Adopt an existing object as a resource, or create it in this state.
* Scope names and URL paths do not always match. Copy `unithandling.unit_manage` and `/unit-handling/{tenant}/units` as written.
---
# 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-terraform.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.