Migrating to Apple Business API v1

Migration Deadline

All partners are required to migrate to Apple Business API v1 by end of October 2026. Business Connect API v3 will no longer be supported after this date.

Overview

This topic describes the steps for partners to migrate to Apple Business API v1.

Additional references:

• Apple Business Partner Guides
• Apple Business API Specification
• Apple Business API Changelog

Migration Timeline

Apple Business API v1 Available now - Apple Business API v1 is available in all three onboarding environments.

For details on the migration process based on your onboarding phase, see Partners Migration Workflow.

Business Connect API v3 vs Apple Business API v1

Changes in Apple Business API v1 that affect production processes, include:

• New API endpoint: Migration from businessconnect.apple.com to api-business.apple.com.

• API version change: From v3 to v1.

• Terminology change: "company"/"companies" terminology is replaced with "organization"/"organizations" throughout.

• URL path changes include:

  • companies → orgs
  • companyId → orgId
  • v3 → v1

• New API documentation: Updated documentation is available at Apple Business Partner Guides.

• Support contact updates: New API support email available maps-partner-support@apple.com.

API Endpoint Migration Examples

The following examples show the endpoint changes from v3 to Apple Business API v1:

Legacy v3 Endpoint (businessconnect.apple.com)

Legacy API v3 Endpoint

https://businessconnect.apple.com/api/v3/companies/{companyId}/locations

New Apple Business API v1 Endpoint (api-business.apple.com)

New Apple Business API v1 Endpoint

https://api-business.apple.com/api/v1/orgs/{orgId}/locations

Partner Migration Workflow

Note: See Troubleshooting and Support for technical questions about the migration.

Partners in AIE or DQE that are Not Approved for Production

For partners that are currently in either AIE or DQE that are not approved for Production release:

1. Before continuing with the API integration, switch from Business Connect API v3 to Apple Business API v1.

2. In AIE, continue testing using Apple Business API v1 endpoints.

3. In DQE, send all locations data using the Apple Business API v1 endpoints.

Partners in DQE that are Approved for Production

For partners who submitted their data for verification using Business Connect API v3 and are approved for launching to production. You have the option to:

• Migrate to Apple Business API v1 now - Complete the steps in the next section, Partners in Production, to complete migration.

• Migrate to Apple Business API v1 later - Continue with API v3 through to production.

  1. Continue with your API onboarding using Business Connect API v3.

  2. Complete Launch to Production using the Business Connect API v3 endpoints.

  3. Then migrate to Apple Business API v1. Complete the steps in the next section, Partners in Production, to complete migration.

Partners in Production

For partners that are currently sending data to production with Business Connect API v3.

1. Switch from Business Connect API v3 to Apple Business API v1.

2. Update API endpoint: businessconnect.apple.com → api-business.apple.com.

3. Update API version: /v3/ → /v1/.

4. Update terminology:

• /companies/ → /orgs/
• /companyId/ → /orgId/
• Update all related parameter names and identifiers

5. Optionally, test using the Apple Business API v1 endpoint in AIE.

6. Optionally, test actual data using the Apple Business API v1 endpoint in DQE. There will be no validation by Apple.

7. If you are using Share Access (OAuth or Delegation), make sure to update all endpoints to use the new domain including the Authorization Code request for OAuth. If applicable, update any images or URLs in your guides.

8. If you are using Webhook for notification, switch your Webhook version in the Business Connect portal under Settings > API. There are no changes on the event types but header values and domain will change.

9. Send data to the production environment using Apple Business API v1.

Migration Checklist

Use this checklist to ensure complete migration:

• API Endpoint: Updated all API calls from businessconnect.apple.com to api-business.apple.com
• API Version: Changed all API paths from /v3/ to /v1/
• Terminology: Replaced companies with orgs in API paths
• Parameter Names: Updated companyId to orgId throughout codebase
• Documentation: Reviewed new API documentation at https://business.apple.com/docs
• Testing: Validated changes in AIE
• Share Access: Updated delegation and OAuth endpoints if applicable
• Webhook: Switched to Apple Business API v1 endpoint on portal if applicable
• Error Handling: Updated error handling for new API responses
• Monitoring: Updated monitoring and logging for new endpoints
• Production: Successfully deployed to production environment

Frequently Asked Questions

When should I start migrating?

You can begin migrating immediately. We recommend starting as soon as possible to allow adequate time for testing and validation.

Will there be any downtime during migration?

No. You can test Apple Business API v1 in parallel with your existing Business Connect API v3 integration. Switch to production when you're ready.

What happens if I don't migrate by the deadline?

After October 31, 2026, Business Connect API v3 will no longer be supported.

Are there any breaking changes beyond the endpoint and terminology updates?

The core API functionality remains the same. The primary changes are the endpoint URL and terminology updates from "companies" to "organization." Refer to Apple Business API Changelog for a list of breaking changes.

Will my existing authentication tokens work with Apple Business API v1?

Yes, your existing authentication mechanisms will continue to work.

Why is v3 changing to v1?

With this change we are introducing a new portal and new domain. The existing Business Connect API endpoints and terminology are being obsoleted by EOS. All new feature development will happen on the new APIs and URLs, starting with version 1.

How do I switch my Webhook version?

You can switch your Webhook version to Apple Business API v1 through the Business Connect portal under Settings > API.