Migrate to Unify V2

Migrating from Unify V1 is primarily an envelope change. Both contracts use the configured source mapping, so your source payload normally remains unchanged.

Recommended approach: migrate and validate in sandbox first, then move production traffic after confirming your mapped values, XML output, error handling, and bulk-processing strategy.

What changes?

Field mapping

For each Unify V1 invoice, make the following changes:

Convert the source object to an alias string:

Unify V1: { "name": "AES", "version": "1" }
Unify V2: "AES:1"

Before: Unify V1

{
  "action": "submit",
  "purpose": "invoicing",
  "env": "sandbox",
  "defaults": {
    "country": "AE",
    "logicalDocumentType": {
      "base": "tax_invoice",
      "modifiers": []
    },
    "source": {
      "name": "AES",
      "version": "1"
    }
  },
  "invoices": [
    {
      "externalId": "INV-1001",
      "payload": {
        "invoice_data": {
          "document_number": "INV-1001"
        }
      }
    }
  ],
  "options": {
    "continueOnError": true
  }
}

Unify V1 requests omit the new-api header or send new-api: false.

After: Unify V2 single request

{
  "country": "AE",
  "environment": "sandbox",
  "purpose": "mapping",
  "source": "AES:1",
  "documentType": {
    "base": "tax_invoice",
    "modifiers": []
  },
  "payload": {
    "invoice_data": {
      "document_number": "INV-1001"
    }
  }
}

Send the new request with:

new-api: true

This example uses mapping to process the document through the Integration Engine. Set purpose to invoicing when sending the document through the invoicing workflow.

After: Unify V2 bulk request

To preserve bulk submission, place the converted, self-contained requests in an invoices array:

{
  "invoices": [
    {
      "country": "AE",
      "environment": "sandbox",
      "purpose": "mapping",
      "source": "AES:1",
      "documentType": {
        "base": "tax_invoice",
        "modifiers": []
      },
      "payload": {
        "invoice_data": {
          "document_number": "INV-1001"
        }
      }
    },
    {
      "country": "AE",
      "environment": "sandbox",
      "purpose": "mapping",
      "source": "AES:1",
      "documentType": {
        "base": "tax_invoice",
        "modifiers": []
      },
      "payload": {
        "invoice_data": {
          "document_number": "INV-1002"
        }
      }
    }
  ]
}

Do not move Unify V1 wrapper fields such as action, defaults, or options into either V2 format. The invoices field is supported by the Unify V2 bulk format, but every item must contain its complete V2 controls rather than inheriting shared defaults. If your mapping expects an external identifier, keep it at its mapped location inside payload; externalId is not a document-level field in the new request.

Per-invoice overrides

A Unify V1 invoice can override shared country, source, and document-type defaults. Unify V2 has no shared defaults, so every document carries its effective controls.

When converting a Unify V1 batch, resolve each invoice's effective values before building the direct request or bulk item:

1. Start with the Unify V1 defaults.
2. Apply any values overridden by that invoice.
3. Place the resulting country, environment, purpose, source, and document type on the direct request or corresponding invoices[] item.
4. Copy that invoice's payload to the same document object unchanged.

Bulk requests

Unify V2 supports one or more documents in an invoices array. Its bulk envelope differs from Unify V1:

• there is no shared defaults object;
• every invoices[] item contains country, environment, purpose, source, documentType, and payload; and
• the request still sends new-api: true as an HTTP header.

Do not reuse the full Unify V1 envelope unchanged. Convert every invoice into a self-contained Unify V2 document item.

Response handling changes

Update your client to use the HTTP status before reading the body:

On success, store documentId. On 422, start with errors[].payloadPath to locate the source value and use errors[].getsPath to understand the mapped canonical field.

See Responses and Errors for the complete response reference.

Recommended rollout plan

1. Inventory Unify V1 behavior. Identify bulk requests, per-invoice overrides, wrapper-level metadata, and dependencies on the V1 response shape.
2. Choose a request format. Build either a direct single-document request or a bulk invoices array of self-contained document requests.
3. Keep the source payload unchanged. Modify it only if sandbox validation identifies a source-data or mapping issue.
4. Choose the purpose. Use mapping for the Integration Engine or invoicing for sending invoices.
5. Add new-api: true. Send it as an HTTP header, not a body field.
6. Update response parsing. Handle direct 200 results, structured 422 findings, and smaller request-error bodies.
7. Test representative documents. Include successful documents, invalid source data, credit notes, an unknown source, and an environment-key mismatch.
8. Verify business outputs. Compare important mapped values and decode the generated XML where your workflow uses it.
9. Test bulk behavior. If you use bulk requests, verify mixed success and failure handling with representative batches.
10. Switch production deliberately. Use a production key, set environment to production, and keep new-api: true enabled.
11. Monitor the rollout. Track HTTP statuses, document IDs, validation codes, and debug request IDs during the transition.

Migration checklist

• Every new request sends new-api: true as an HTTP header.
• env has been renamed to environment.
• Each document uses mapping for the Integration Engine or invoicing for sending invoices.
• For single requests, document controls and one source payload are at the request root.
• For bulk requests, every invoices[] item contains its complete document controls and payload.
• Source name and version are combined as name:version for every document.
• Unify V1 defaults, action, and options fields are not sent to Unify V2.
• API keys match the requested environment.
• The client handles HTTP 422 as a validation outcome.
• documentId is stored on successful processing.
• Bulk requests have been tested with representative documents and failure cases.
• Sandbox outputs have been verified before production rollout.

Need to remain on Unify V1 temporarily?

Unify V1 remains documented for compatibility. Continue using it by omitting new-api or sending new-api: false:

• Unify V1 Integration Guide
• Unify V1 Examples
• Unify V1 Error Codes
• Unify V1 Submission and Retrieval Flow

Avoid adding new dependencies on the Unify V1 envelope. Use Unify V2 for new development while you complete the migration.