> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nymble Commerce API FAQ: Frequently Asked Questions Answered

> Answers to common questions about Nymble Commerce's B2B commerce API, including authentication, pricing, integrations, and data management.

Find answers to common questions about using Nymble Commerce. If you can't find what you need, contact support.

## Getting started

<AccordionGroup>
  <Accordion title="What are the API base URLs?">
    Nymble Commerce provides two environments:

    | Environment | Base URL                              |
    | ----------- | ------------------------------------- |
    | Production  | `https://api.achievemomentum.com`     |
    | Sandbox     | `https://api-dev.achievemomentum.com` |

    Use the sandbox environment for development and testing. It is functionally identical to production but operates on isolated data, so changes you make there have no effect on your live org.
  </Accordion>

  <Accordion title="How do I get my ClientId and ClientSecret?">
    Your `ClientId` and `ClientSecret` are provisioned when your Nymble Commerce account is created. Contact your account manager if you have not received them or if you need to rotate your credentials.
  </Accordion>

  <Accordion title="Is there a sandbox environment?">
    Yes. The sandbox is available at `https://api-dev.achievemomentum.com`. It runs the same API version as production and supports all the same endpoints, but its data is completely isolated from your production org. Use it freely for integration testing, demos, and development without risk of affecting live records.
  </Accordion>

  <Accordion title="What authentication method should I use for server-to-server integrations?">
    Use an API key passed in the `x-api-key` request header. API key authentication is designed for machine-to-machine (M2M) scenarios — there is no token expiry to manage, no refresh flow to implement, and the key carries the same organizational scope as a login token. Reserve credential-based login for interactive or user-facing flows.
  </Accordion>
</AccordionGroup>

***

## Catalog and pricing

<AccordionGroup>
  <Accordion title="How does customer-specific pricing work?">
    Each customer has a price tier encoded as a claim in their access token (`PriceTier`). Products in Nymble Commerce support multiple `PricePoints`, one per tier. When your application calls a product or catalog endpoint, Nymble Commerce reads the `PriceTier` claim from the token and automatically returns the matching price — you do not need to select or filter prices in your own code.
  </Accordion>

  <Accordion title="Can I have multiple currencies?">
    Yes. `CurrencyCode` is set at the customer level and flows automatically through orders and invoices. When a customer's token includes a `CurrencyCode` claim, all monetary values returned by the API for that customer will reflect the correct currency. You do not need to pass a currency parameter on individual requests.
  </Accordion>

  <Accordion title="Can I import products in bulk?">
    Yes. Send a `POST` request to `/api/products/bulk` with an array of product records. Use the `ExternalId` field to make your imports idempotent — if you re-import a product with the same `ExternalId`, Nymble Commerce updates the existing record rather than creating a duplicate. This makes it safe to run recurring sync jobs from your PIM or ERP without generating conflicts.
  </Accordion>
</AccordionGroup>

***

## Orders and invoices

<AccordionGroup>
  <Accordion title="Can I import historical orders?">
    Yes. Use `POST /api/orders/bulk` and include an `ExternalId` on each order. If you re-submit an order with an `ExternalId` that already exists in Nymble Commerce, the API updates the existing order rather than creating a new one. This makes bulk imports safe to run multiple times during a migration.
  </Accordion>

  <Accordion title="How do I link an order to an invoice?">
    Nymble Commerce links them automatically — completing a checkout creates both an order and a corresponding invoice in a single operation. You can retrieve the invoice for a given order by calling `GET /api/invoices?orderId={orderId}`, or by reading the `OrderId` field on the invoice object.
  </Accordion>

  <Accordion title="Can I partially pay an invoice?">
    Yes. Record a payment for any amount less than or equal to the invoice total. After a partial payment is recorded, the invoice status changes to `PartiallyPaid` and the outstanding balance is updated accordingly. You can record additional payments until the balance reaches zero, at which point the invoice moves to `Paid`.
  </Accordion>

  <Accordion title="What is the difference between void and cancel?">
    **Void** removes the invoice from accounts receivable entirely — it is as if the invoice never existed for reporting and AR purposes. **Cancel** marks the invoice as cancelled but keeps the record in your data for audit and historical traceability. Use void when the invoice was created in error; use cancel when you need a permanent record of the cancellation.
  </Accordion>
</AccordionGroup>

***

## Payments

<AccordionGroup>
  <Accordion title="Do you support ACH / bank transfers?">
    You can record ACH and bank transfer payments as offline payments using the record-payment endpoint. Direct ACH processing (initiating the bank transfer through Nymble Commerce) depends on your payment provider configuration — contact your account manager to discuss enabling a provider that supports ACH origination.
  </Accordion>

  <Accordion title="Is it safe to store card data?">
    Yes. Nymble Commerce never stores raw card numbers. When a customer saves a payment method, the card data is sent directly to your payment provider, which tokenizes it and returns a token (`PaymentProfileId`). Nymble Commerce stores only the token — no sensitive card data ever touches Nymble Commerce's storage.
  </Accordion>

  <Accordion title="Can customers save multiple cards?">
    Yes. Each call to the save-method endpoint creates a new `PaymentProfileId` for the customer. To list all saved payment methods for a customer, call `GET /api/payments/profiles/{customerNumber}`. Your customers can then select from their saved methods at checkout.
  </Accordion>
</AccordionGroup>

***

## Integrations

<AccordionGroup>
  <Accordion title="How do I connect QuickBooks?">
    Create a QuickBooks integration record via the Nymble Commerce API, then follow the OAuth authorization flow to grant Nymble Commerce access to your QuickBooks Online account. Once authorized, Nymble Commerce can sync customers, invoices, and payments with QuickBooks automatically. See the [integrations guide](/guides/integrations) for step-by-step instructions.
  </Accordion>

  <Accordion title="Can I add a custom payment provider?">
    Yes. Nymble Commerce supports custom payment gateway integrations. Contact your account manager to discuss adding a provider for your preferred payment gateway.
  </Accordion>
</AccordionGroup>

***

## Security and data

<AccordionGroup>
  <Accordion title="Can one organization access another's data?">
    No. All data in Nymble Commerce is strictly isolated by `OrganizationId`. Every request is validated against the `OrganizationId` claim in your token, and the API enforces this boundary on every endpoint — there is no way for a token issued to one org to read or modify another org's data.
  </Accordion>

  <Accordion title="How long are document CDN URLs valid?">
    CDN URLs for Company Docs are signed and expire after **1 hour**. If you store a `cdnUrl` from an earlier API response and need to display or serve the document more than an hour later, call `POST /api/companydocs/documents/{documentId}/refresh-url` to generate a new signed URL.
  </Accordion>

  <Accordion title="What is the maximum file size for Company Docs uploads?">
    The maximum file size per upload is **50 MB**. Files are virus-scanned before being stored. If your use case requires larger files, contact your account manager.
  </Accordion>
</AccordionGroup>