Extension Points

Keep the PunchOut package unchanged. Add project-specific behavior in a separate Magento module through dependency injection, plugins, service contracts and events. This keeps Composer updates predictable and separates customer-specific integration code from the product.

Public service contracts

Use these interfaces for the main integration workflows:

Interface	Purpose
`MageB2B\Punchout\Api\ContextManagerInterface`	Creates and reads PunchOut session contexts.
`MageB2B\Punchout\Api\TransferServiceInterface`	Prepares the cart return for OCI or cXML.
`MageB2B\Punchout\Api\ProtocolAdapterInterface`	Defines protocol-specific cart output.
`MageB2B\Punchout\Api\InboundOrderManagementInterface`	Processes and manages inbound cXML orders.
`MageB2B\Punchout\Api\InboundOrderRepositoryInterface`	Reads durable inbound-order records.
`MageB2B\Punchout\Api\JitCustomerProvisionerInterface`	Creates customers for JIT e-mail mapping.
`MageB2B\Punchout\Api\OciProductIdentifierInterface`	Resolves the configured OCI external product identifier.
`MageB2B\Punchout\Api\OrderLineMetadataResolverInterface`	Resolves external line numbers and units for outbound documents.
`MageB2B\Punchout\Api\OutboundDocumentEndpointResolverInterface`	Resolves the effective Confirmation, ASN or Invoice endpoint.
`MageB2B\Punchout\Api\Bridge\ActorResolverInterface`	Supplies project-specific actor context.
`MageB2B\Punchout\Api\Bridge\PermissionGuardInterface`	Applies project-specific transfer permissions.

Prefer a plugin when the standard service already performs the required workflow and you only need to adjust its input or result. Use a preference only when your implementation must replace the complete contract.

Lifecycle events

Event	When to use it
`punchout_actor_resolve_before`	Add actor candidates before actor resolution.
`punchout_actor_resolve_after`	Read the resolved actor context and source.
`punchout_permission_check_before`	Add project data before transfer authorization.
`punchout_permission_check_after`	React to a successful permission check.
`punchout_transfer_prepare_before`	Add data before Magento prepares the cart payload.
`punchout_transfer_prepare_after`	Inspect or extend a valid prepared transfer result.
`punchout_transfer_success`	React after Magento has generated the handoff payload. This event does not prove that the receiving browser processed it.
`punchout_customer_authentication`	React after Magento has checked customer status, lock state and confirmation.
`punchout_inbound_identity_resolved`	Adjust normalized identity data before customer mapping.
`punchout_jit_customer_created`	React after PunchOut creates a Magento customer through JIT provisioning.
`punchout_inbound_address_resolved`	Adjust a resolved billing or shipping address before quote assignment.
`punchout_inbound_order_processed`	React after inbound-order processing has reached its result.
`punchout_cxml_order_request_build_before_serialize`	Add supported cXML data to the mutable document before serialization.
`punchout_mapping_source_field_options`	Add fields to an Admin mapping source.
`punchout_mapping_context_values`	Supply runtime values for context mapping rules.
`punchout_document_order_after`	React to a Magento order document event with durable PunchOut context.
`punchout_document_shipment_after`	React to a shipment document event.
`punchout_document_invoice_after`	React to an invoice document event.
`punchout_document_event`	Handle order, shipment and invoice events through one common event.

Observers should remain small and must not modify stored credentials or unsanitized trace data. Put substantial integration logic behind an injected service and call that service from the observer.

Mapping extensions

Use punchout_mapping_source_field_options to expose a new typed source field in Magento Admin. Supply its runtime value through punchout_mapping_context_values. This keeps the mapping editor and runtime evaluation in sync.

Protected protocol fields remain owned by PunchOut. For example, the OCI external product ID comes from the buyer profile and cannot be replaced by an ordinary mapping rule.