> For the complete documentation index, see [llms.txt](https://docs.archera.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archera.ai/help-center/archera-embedded/onboard-a-customer-via-gcp.md).

# Onboard a Customer via GCP

Register a customer organization and set up GCP cloud integration using the Archera Partner API

Use the Archera Partner API to programmatically onboard customers and set up GCP cloud integration.

**Prerequisites**:

* Partner API key and partner organization ID
* Contact your Archera representative if you don't have these credentials
* Customer must have a Google Cloud organization, the three billing exports, and an administrator who can run the install. Step 2 returns the full checklist.

**Base URL:** `https://api.archera.ai/v2`

**Authentication:** Include `x-api-key: YOUR_PARTNER_API_KEY` header in all requests.

The examples use shell variables. Set them once, with your real values, before you run any command:

```shellscript
export PARTNER_API_KEY="your-partner-api-key"
export PARTNER_ORG_ID="your-partner-organization-id"
```

***

### Step 1: Register the customer organization

```shellscript
curl -X POST \
  -H "x-api-key: $PARTNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Corp",
    "users": [{"email": "admin@acmecorp.com", "role": "admin"}]
  }' \
  https://api.archera.ai/v2/partners/$PARTNER_ORG_ID/orgs
```

**Save from response:** `id`. This is the customer organization ID:

```shellscript
export CHILD_ORG_ID="id-from-the-response"
```

***

### Step 2: Get the install command

```shellscript
curl -X POST \
  -H "x-api-key: $PARTNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "gcp_organization_id": "123456789012",
    "gcp_project_id": "acme-billing",
    "gcp_billing_account_id": "0A1B2C-3D4E5F-6A7B8C",
    "gcp_billing_dataset": "billing_export",
    "gcp_pricing_dataset": "billing_export",
    "gcp_cud_dataset": "cud_export"
  }' \
  https://api.archera.ai/v2/org/$CHILD_ORG_ID/partners/onboarding/gcp/install-command
```

Add `"read_only": true` to onboard without purchase permissions. Archera can then read cost data and commitments but cannot buy or exchange them.

The response has three fields:

* `command`: a `gcloud storage cat ... | bash` command. **Send it to your customer.** Someone with Organization Administrator on their GCP organization runs it in Cloud Shell. Archera cannot run it for them.
* `prerequisites`: a checklist to send with the command. Each item is a reason the install would otherwise fail.
* `prerequisites_url`: the same checklist as a web page.

***

### Step 3: Verify GCP integration

After the customer has run the command:

```shellscript
curl -X POST \
  -H "x-api-key: $PARTNER_API_KEY" \
  https://api.archera.ai/v2/org/$CHILD_ORG_ID/partners/onboarding/gcp/verify
```

**Check response:** a list of `{feature, status, detail}` entries. `detail` says what is outstanding. Onboarding is complete once `gcp/feature/cur/connected` is `available`.

* `gcp/feature/cur/available` can stay `missing` for up to 48 hours while Google writes the billing exports. It clears on its own.
* On a read-only install, `gcp/feature/purchase-access` is `missing` by design.

Safe to call again at any time.

***

### Errors

Error responses carry a stable `error` code to branch on. Every `message` is safe to show the customer.

| Status | `error`                                                        | Meaning                                                                                                                                                                                                     |
| ------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 422    | `validation_error`                                             | Step 2: a field is missing or not in Google's format. `errors.query` names it.                                                                                                                              |
| 400    | `gcp_onboarding_field_missing`, `gcp_onboarding_field_invalid` | Step 3: Step 2 has not been completed. `errors` names the field.                                                                                                                                            |
| 400    | `gcp_org_access_denied`                                        | Archera cannot read the GCP organization. Either the customer has not run the command yet, or an organization policy is blocking Archera's service account. Archera cannot tell these apart, so check both. |
| 400    | `gcp_validation_failed`                                        | Something else the customer must fix, such as a dataset or export table Archera cannot see. `message` says which.                                                                                           |
| 409    | `gcp_onboarding_project_mismatch`                              | This GCP organization is already onboarded from a different project. Use the original project, or contact Archera support.                                                                                  |

***

### What You Can Do

The Archera Partner API enables you to:

* **Register customer organizations** under your partner account
* **Set up GCP cloud integration** with a command your customer runs
* **Verify integration status** and data collection
* **Access commitment recommendations** for your customers
* **Execute purchases** on behalf of customers

This allows you to build Archera's cost optimization capabilities directly into your platform.


---

# 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://docs.archera.ai/help-center/archera-embedded/onboard-a-customer-via-gcp.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.
